Troubleshooting

Most problems in AgenC Desktop come from one of three places: the app cannot reach AgenC Core, a provider refuses a request, or the operating system blocks something. This page goes symptom by symptom. When nothing here helps, Feedback in the account menu opens the AgenC Core issue tracker on GitHub.

Installation errors

The examples use a placeholder code. Replace it with the code you received. Do not post your code or a download URL in a bug report. Include the platform, version, HTTP status and error text with personal paths removed.

Download responses from agenc.ag

The installers now print agenc.ag's message with an AgenC: prefix. For example, a used code prints AgenC: This invitation code was already used. The message is limited to 200 printable ASCII characters on one line. Nothing is installed when the invitation request fails. Use the same platform during the 30-minute retry window.

If a response has no message body, the installer prints AgenC: Download failed (HTTP STATUS). Nothing was installed. Retry later on the same platform. Include the status if you report the failure.

AgenC: Could not reach agenc.ag. Please try again. Nothing was installed. means the invitation request could not complete. Check your connection and retry on the same platform.

AgenC: Download redirect must be an absolute HTTPS URL. Nothing was installed. means the download response had a missing or invalid address. Stop and report it to your inviter. Do not change the script to allow it.

Script messages

Script refusals start with AgenC:. The messages below omit that prefix. Values such as PATH, VERSION and ARCH stand for the value printed on your computer. The scripts reject a malformed code before requesting a file. They cannot tell you whether a correctly formatted code is accepted until agenc.ag answers.

macOS installer refusals

• AgenC Desktop is invitation-only right now. Run this with your invitation code: curl -fsSL https://get.agenc.ag/desktop.sh | sh -s -- AGNC-XXXXX-XXXXX-XXXXX-XXXXX. Run the command from the install guide with your own code as the trailing argument. The placeholder cannot download the app.
• This invitation code is not valid. Copy the code exactly, including uppercase letters and hyphens. Replace the example placeholder.
• This installer is for macOS only. See https://agenc.ag/core. Use the command for your operating system in the install guide.
• Run as your normal user, without sudo. Open a normal Terminal and run without sudo.
• macOS 13.5 or later is required. Use a Mac running macOS 13.5 or later.
• Unsupported architecture: ARCH Use a supported machine and the matching shell. macOS supports Apple silicon and Intel; Windows requires x64.
• Usage: sh desktop.sh INVITATION_CODE [--destination /absolute/Applications] Use the complete command from the install guide. Only macOS accepts --destination after the code.
• Destination must be an absolute directory. Pass an absolute, writable folder after --destination.
• Already installed at PATH. Quit AgenC and move that app to Trash before reinstalling. Quit AgenC. Move the indicated app to the Trash, then rerun the command. Keep the data folder.
• AgenC is already in /Applications. Quit it and move that app to Trash before reinstalling. Quit AgenC and move /Applications/AgenC.app to the Trash before retrying.
• Download checksum mismatch; nothing installed. Nothing was installed by this attempt. Fetch the latest script and retry on the same platform. If the mismatch repeats, report it to your inviter. Do not bypass the checksum.
• The disk image does not contain AgenC.app. Download again on the same platform. If it repeats, report the damaged or incorrect image to your inviter.
• Unexpected quarantine attribute. Use the DMG and Privacy & Security > Open Anyway instead. Use the invitation DMG download and the Privacy & Security > Open Anyway steps. The script will not clear quarantine.
• Another installation appeared; it was left unchanged. Check the destination in Finder. A copy appeared during the download and was left unchanged. Quit it and remove it only if you intend to reinstall.

Windows installer refusals

• AgenC Desktop is invitation-only right now. Run this with your invitation code: & ([scriptblock]::Create((irm https://get.agenc.ag/desktop.ps1))) AGNC-XXXXX-XXXXX-XXXXX-XXXXX. Run the command from the install guide with your own code as the trailing argument. The placeholder cannot download the app.
• This invitation code is not valid. Copy the code exactly, including uppercase letters and hyphens. Replace the example placeholder.
• Already installed or occupied: PATH. Quit AgenC and uninstall it in Settings before reinstalling. A leftover directory must be moved aside manually. Quit and uninstall AgenC in Settings > Apps. Move leftover files aside manually. An empty ordinary folder is allowed after uninstall.
• An existing AgenC installation is registered. Quit AgenC and uninstall it in Settings before reinstalling. A machine install may need its administrator to remove it. Uninstall through Settings > Apps. Ask the administrator to remove a machine install. Do not delete registry entries to bypass the check.
• AgenC is running. Quit it before installing; no process will be stopped for you. Quit AgenC, including any remaining AgenC processes, then retry. The script does not stop them.
• Refusing a non-HTTPS download or redirect. Stop and report the unexpected redirect to your inviter. Do not change the script to allow it.
• Download returned no response. Check the connection and retry. Report the failure if it continues.
• Download failed; nothing installed. Check your connection and the HTTP response table above. Retry the same platform within the invitation window.
• Download failed: HTTP STATUS. Check your connection and the HTTP response table above. Retry the same platform within the invitation window.
• Download redirect has no Location. Retry later. Report the incomplete download response if it continues.
• Too many download redirects. Retry later. Report the redirect loop if it continues.
• This installer is for Windows only. Use the command for your operating system in the install guide.
• PowerShell 5.1 or later is required. Open 64-bit PowerShell 5.1 or later.
• Windows 10 or 11 is required (desktop editions). Use Windows 10 or 11 desktop editions. Windows Server is refused.
• Unsupported architecture: ARCH. Release 0.1.12 publishes Windows x64 only. Use a supported machine and the matching shell. macOS supports Apple silicon and Intel; Windows requires x64.
• Use 64-bit PowerShell from the Windows Start menu. Open the native 64-bit PowerShell from Start.
• Cannot determine whether this shell is elevated. Run whoami.exe /groups in normal PowerShell. Ask your administrator if system policy prevents it.
• Run in a normal PowerShell window, not as administrator. Close the administrator window and open normal PowerShell.
• LOCALAPPDATA must be an absolute per-user directory. Use your normal Windows account with a valid absolute LOCALAPPDATA path. Ask your administrator to repair the user environment if needed.
• A machine AgenC installation or occupied path exists at PATH. Uninstall it in Settings before reinstalling; move leftover files aside manually. Uninstall in Settings > Apps. A machine install may need its administrator. Move any nonempty leftover folder aside manually.
• Download checksum mismatch; nothing installed. Nothing was installed by this attempt. Fetch the latest script and retry on the same platform. If the mismatch repeats, report it to your inviter. Do not bypass the checksum.
• The download has Mark-of-the-Web. Nothing installed; no security attribute was removed. Use the browser-downloaded invitation installer and its normal Windows prompts. The script refuses this file and removes no security attribute.
• Installer failed (exit NUMBER). It may have left a partial install; inspect Settings > Apps and PATH before retrying. Inspect Settings > Apps and the named folder for a partial install. Uninstall or move leftovers aside before retrying.
• Installer returned success but AgenC.exe is missing at PATH. Inspect Settings > Apps before retrying. Inspect Settings > Apps and the destination. Report the missing executable; resolve partial state before retrying.

Linux installer refusals

• AgenC Desktop is invitation-only right now. Run this with your invitation code: wget -qO- https://get.agenc.ag/desktop-linux.sh | sh -s -- AGNC-XXXXX-XXXXX-XXXXX-XXXXX (or curl -fsSL https://get.agenc.ag/desktop-linux.sh | sh -s -- AGNC-XXXXX-XXXXX-XXXXX-XXXXX). Run the command from the install guide with your own code as the trailing argument. The placeholder cannot download the app.
• This invitation code is not valid. Copy the code exactly, including uppercase letters and hyphens. Replace the example placeholder.
• This installer is for Linux only. See https://agenc.ag/core. Use the command for your operating system in the install guide.
• Usage: wget -qO- https://get.agenc.ag/desktop-linux.sh | sh -s -- INVITATION_CODE (or curl -fsSL https://get.agenc.ag/desktop-linux.sh | sh -s -- INVITATION_CODE) Use the complete command from the install guide. Only macOS accepts --destination after the code.
• Release 0.1.12 publishes 64-bit Intel or AMD Linux only; there is no ARM build. Use an x86_64 Linux machine. There is no Linux ARM artifact.
• This installer needs apt (Debian, Ubuntu and their derivatives). Other distributions need the AppImage and a separate invitation download. Use Ubuntu 24.04+ or Debian 13. Other compatible distributions need the AppImage and a separate platform claim.
• Required command missing: COMMAND. Install the named system tool through your distribution, then retry.
• This system does not install amd64 packages. Use an amd64 package system. A different Debian package architecture is not supported.
• glibc 2.38 or later is required; musl is not supported. Use a supported distribution with glibc 2.38+. Do not replace your system libc manually for this app.
• glibc 2.38 or later is required. Use a supported distribution with glibc 2.38+. Do not replace your system libc manually for this app.
• Cannot determine the glibc version. Check getconf GNU_LIBC_VERSION. Use a supported glibc distribution if it fails or returns an unexpected value.
• glibc 2.38 or later is required; this system has VERSION. Nothing installed. Use a supported distribution with glibc 2.38+. Do not replace your system libc manually for this app.
• curl or wget is required to download the package. Install curl or wget through your distribution, then retry.
• Installing a package needs sudo. Run this as root or ask your administrator. Ask your administrator to install the package, or use an account allowed to use sudo.
• Download failed; nothing installed. Check your connection and the HTTP response table above. Retry the same platform within the invitation window.
• Download checksum mismatch; nothing installed. Nothing was installed by this attempt. Fetch the latest script and retry on the same platform. If the mismatch repeats, report it to your inviter. Do not bypass the checksum.
• The package was not installed. If sudo refused, check that you may use sudo. If apt could not find dependencies, run "sudo apt-get update" and try again. Check sudo access and apt output. For missing dependencies, run sudo apt-get update and retry. A package failure may require your administrator to repair apt state.
• apt finished, but agenc-desktop reports version VERSION. Inspect dpkg-query -W agenc-desktop and the apt output. Ask your administrator to resolve the reported package state before retrying.

Progress and successful exits

These lines are informational. Paths and installed versions vary.

System tools can also print their own errors. curl or wget can fail before any script arrives, or while downloading the installer. macOS can report errors from hdiutil, codesign, ditto, mktemp or file permissions. Windows can report PowerShell, filesystem or process-start errors. Linux can report sudo, apt, package-lock or dependency errors. Read that output before retrying. Do not skip checksum, code-seal or security-attribute checks. A failed apt or Windows installer can leave partial package state.

The app does not open

• macOS says "AgenC.app Not Opened". The app is not notarized yet. Choose Done, then System Settings > Privacy & Security > Open Anyway. See Install and update.
• Windows warns about an unknown publisher. Choose Keep, then More info and Run anyway when those options are offered. Smart App Control and organization policy may block an unsigned app without an override.
• Linux: nothing happens, or the app quits at once. Check that your system has glibc 2.38 or newer with ldd --version: Ubuntu 24.04 or newer, or Debian 13. On Ubuntu 24.04 and later the AppImage quits at launch; install the .deb instead. On a minimal system, install the current .deb with apt so it pulls in the libraries it needs.

The loading screen does not go away

The loading screen shows what the app waits for. When Core fails to start, it shows the reason, with Try again and Open anyway; the same buttons appear after a minute.

• Try again reconnects and starts the app's Core if it is not running.
• Open anyway shows the app, so you can reach Settings.
• "Packaged AgenC Core runtime is missing" or an integrity check failure means the installation is damaged. Install the app again; your data stays.
• On Linux, Core refuses to start when its data folder, or a folder above it, can be changed by other users of the group ("protected directory chain permits untrusted mutation"). An older AppImage could create it that way. Remove that write access, for example with chmod 700 ~/.config/AgenC, then open the app again.

"Connecting…" or "Reconnect daemon"

The sidebar shows "Connecting…" or Reconnect daemon when the app has lost Core, and the chat says "Daemon offline: sessions keep their transcript; reconnect to continue." The app retries on its own every few seconds.

• Click Reconnect in the banner, Reconnect daemon in the sidebar, or press Ctrl/Cmd+R. Reconnecting starts the app's Core if it stopped; it does not restart a Core that is running.
• Settings > Advanced > Daemon shows the connection's status and address, with Reconnect.
• To restart Core itself, quit AgenC and open it again. After you remove a provider key, Settings > Providers also offers Restart daemon.

A session stopped or did not answer

• "The daemon stopped during this turn." Core stopped while the agent worked. Click Continue to let the agent pick up where it stopped.
• "The turn ended with no answer." Click Retry, or Switch model if the model keeps failing. The note shows the reason Core gave, when there is one.
• "Continued from" a session. The agent behind the old session ended, and the app moved your message into a fresh session.
• The session waits for a review. After a crash, Core may not know what a tool call did. Record it with /resolve; see Sessions and projects.
• Your message went into a queue. A turn was still running. The queue sends it when the turn ends; Steer sends it now. See Writing messages.

A session will not start

• "Choose a project before starting this session." Pick a folder with the workspace chip above the composer, or choose "Don't work in a project".
• "Choose a project folder other than your home directory." Your home folder cannot be a project. Pick a folder inside it.
• Windows: "AgenC needs Git Bash to run sessions on Windows". Install Git for Windows in its default location and restart AgenC, or set AGENC_SHELL to the full path of its bash.exe.

A provider fails

• Every call asks for approval. The folder is not trusted and the session is in "Ask for every tool". Answer Allow for session, or see Permissions and approvals.
• "Model discovery failed. Try again." The provider did not answer the model list. Check the key and your connection, then click Fetch list in the model picker.
• The card says a saved key is not used. An environment variable points the provider at another server. The card says which variable to unset.
• "Default not changed". A provider without working credentials cannot become the default. Connect it first.
• Fast is missing for Grok. Fast needs an xAI API key. A Grok account signed in with X does not offer it.
• Fewer OpenAI models than expected. A ChatGPT sign-in reaches fewer models than an API key.
• A removed key still works. Core keeps it until it restarts. Click Restart daemon.
• "Secure OS key storage is unavailable." On Windows and Linux the app saves keys only when the system's secure storage works. On Linux, make sure your desktop keyring is running and unlocked.

The configuration looks wrong

Settings > Advanced > config.toml > Validate asks Core to check the file and says "Configuration valid" or what is wrong, for example "Invalid TOML syntax in config.toml at line 12." Open opens the file; Reload applies it without restarting Core.

Voice input does not work

• The first run stops at the speech model. The first run needs an internet connection to download it. Check the connection and click retry setup.
• "Whisper's local engine is unavailable." Open Settings > Whisper and click Refresh. Reinstall the app if it stays unavailable.
• The microphone stops by itself. Whisper stops when you switch chats, open Settings, hide the window or reconnect Core. Turn it on again.
• A phrase was not sent. It waits as an "Unsent voice message" in the chat and in Settings > Whisper, with Retry send and Copy text.

Routines do not run

Routines run only while the computer is awake and the app's Core is running. Check that:

• the routine is enabled, not paused;
• AgenC is open. On Windows and Linux, closing the last window quits it;
• the computer was awake at the scheduled time. Missed runs are not run later.

The run history says why a run failed or waited for permission.

A phone cannot connect

• Sign in to your AgenC account on the computer first.
• Share a chat that is in "Ask for every tool" or plan mode, and that has a project folder.
• The QR code expires after a few minutes, and only one invitation can be open. Click Refresh QR.
• Approve the device on the computer when it asks.

An update does not arrive

0.1.6 is not offered invitation-only 0.1.12 in the app. Clicking Check for updates again will not redeem your invitation. Follow Updating to 0.1.12. Windows needs an uninstall first. macOS needs the old app moved to the Trash. The Linux command upgrades the .deb. Replace an AppImage with the new download. Chats, settings and keys stay.

For signed-feed checks, "Could not check for updates. Check your connection and try again." means the feed could not be reached. An unverifiable feed has a separate error. Automatic checks may be off in Settings > General. Neither a successful check nor an up-to-date status grants invitation access.

The app writes each update step to updates.log in its data folder; see Data and privacy.