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.

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.
• 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

• Versions 0.1.4 and earlier never check. Install the new version by hand once.
• A Linux .deb does not update itself. Run the install command again.
• On macOS the app opens the download page instead of installing.
• Check for updates automatically may be off. Click Check for updates.
• "Could not check for updates. Check your connection and try again." means the release feed could not be reached. When the feed cannot be verified, the message says so instead.

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