Troubleshoot Codity Agents

Use the agent's dashboard transcript and its terminal output together to identify whether a problem is in setup, permissions, provider access or recovery.

Deploy agent is disabled

Check the form's requirement message. The dashboard requires a nonempty name, selected provider/model and model API key. The name is prefilled but must not be cleared. Headless mode also needs a task; Interactive (TUI) may leave it empty. Broad command permissions need their acknowledgement before deployment.

Premium is not required for the Agents form. If the model list cannot load, resolve the reported connection or service error before deploying.

Failed to mint install script

No install command was created, so the problem happened before the agent started on your machine. Retry from the agent page and check the failing install-script request's status/message in your browser's Network panel.

Possible causes include a revoked or missing configuration, an expired dashboard login, an unavailable agent service, an unsupported target, or a missing binary for the selected OS. If the response remains a generic server error, share the request time, response status and agent ID with your administrator. Do not share provider keys or install tokens. Self-hosted administrators should verify agent-service connectivity and hosted binaries.

Install token expired or already used

One machine bootstrap commands expire after five minutes and are consumed on the first handshake. Generate a fresh command rather than rerunning the old one. Many machines commands remain reusable until their expiry, install cap or revocation.

Use codity-agent resume --last to recover a saved session. A fresh install command starts a new run; it does not resume an old one.

codity-agent: command not found

The agent installer creates ~/.local/bin/codity-agent by default. Verify it directly:

"$HOME/.local/bin/codity-agent" --help

If it works, include ~/.local/bin in your shell's PATH. If you set CODITY_AGENT_BIN_DIR, use that location. Installing the main codity CLI alone does not install this runner; it is installed when an agent starts through the agent installer.

File edits or commands are refused

Inspect Setup on the agent page for individual and inherited permissions. Match the exact path on the machine, grant Write for edits, and check for a shared deny. Prefer absolute paths. A Read permission will not allow apply_patch or other file edits.

Shell commands require command permissions separately. A file allow does not grant ls, cat, sleep or git status. An agent may use allowed file tools after a shell attempt is refused. In Ask me mode, approve an eligible request in the dashboard or through codity agent approvals; an explicit deny cannot be bypassed by approval.

Updated rules apply to a fresh run or resume. An already running session keeps its earlier snapshot. See Permissions and YAML policies.

Policy editor is read-only or save conflicts

Only account administrators can change organization or team policies. Ask an account administrator to update the policy or your role, then refresh after a role change. If the editor reports that the policy changed, reload the saved revision, review it and save again.

An invalid YAML version or field is a validation failure. Use version: 1 and the rule fields from the policy guide.

Model authentication fails

Use the key for the selected provider and confirm that it can access the selected model. Check provider quota and billing as well as authentication. A Codity API key is not an OpenAI or Anthropic model key.

The runner may ignore an inherited provider base URL when Codity supplies a key intended for that provider's own endpoint. If you deliberately use a gateway, declare its base-URL variable in Already set on the machine and verify that the supplied key is intended for that gateway.

Permission suggestions are separate from your agent's model connection. A suggestions error does not prevent you from entering permissions manually. If suggestions remain unavailable, contact your administrator to check the dashboard's OpenAI connection.

Resume cannot find or use a session

Run codity-agent sessions from the original folder, or codity-agent sessions --all to locate another folder's saved session. Use the listed run ID, not the configuration ID from the dashboard URL.

Recovery must have been enabled and a checkpoint saved before the stop. If local records are missing, try the dashboard recovery panel. A live local process, a revoked configuration, a dashboard stop, an expired checkpoint or an already resumed source may prevent recovery. An unfinished action requires review; a changed workspace requires reconciliation. Follow Session recovery.

Messages do not reach a stopped run

Dashboard and API messages reach a live agent through its next heartbeat. They do not start a process. Check the run status and last-seen time. Resume the session with a follow-up prompt or start a fresh run if it has already ended.