Troubleshooting

When something goes wrong, Cusp tries to say what happened, why, and what to do. If a message doesn't make that clear, that is a bug; please report it.

Two commands help with almost everything:

• /status in the CLI shows the daemon connection, the session, the model and the workspace.
• cusp --verbose prints diagnostics to stderr, including connection attempts and, in headless mode, every permission denial.

Keys and providersCopy Anchor Link

"Couldn't detect a provider for this key"Copy Anchor Link

Cusp recognizes many keys by their prefix, but some providers (DeepSeek, Moonshot, Z.ai, MiniMax, Mistral and others) use keys without a distinctive prefix. Enter the provider's base URL along with the key. See the URLs in Providers and gateways.

401 or 403 from the providerCopy Anchor Link

• Check that the key is active in the provider's console and has credit or quota.
• Some providers issue separate keys for separate products. A Z.ai coding plan key, for example, works only on the coding plan endpoint.
• For gateways, check that the key has access to the model you selected.

"Rate limited by … — retrying in 8 s"Copy Anchor Link

The provider is throttling requests. Cusp retries with backoff on its own. If it keeps happening, lower the effort, switch to a model with higher limits, or configure a fallbackModel.

The model doesn't call tools, or calls them wrongCopy Anchor Link

• Make sure the model supports tool calling. Cusp's catalog marks models that don't, and won't pick them automatically.
• For local models, check the server's context length. Many runtimes default to 4k or 8k tokens, which isn't enough for an agent; set at least 32k.
• Small models do better with Cusp's line-anchored edit format. This is chosen automatically for models Cusp recognizes as weaker; for an unknown model id it may not be.

Costs look highCopy Anchor Link

• Check /cost. If cache reads are near zero, the prompt cache isn't being hit. Switching models or providers mid-session starts a cold cache.
• Lower the effort for routine work.
• Use a smaller model for subagents that do broad searches.

The daemonCopy Anchor Link

The CLI says it can't reach the daemonCopy Anchor Link

• With the default --daemon auto, the CLI starts its own daemon if none is running. If that fails, run with --verbose to see why.
• With --daemon connect, check --daemon-url and --daemon-token (or CUSP_DAEMON_URL and CUSP_DAEMON_TOKEN). The token must be the one that daemon was started with.
• Try --daemon embedded, which runs the daemon inside the CLI process and avoids networking entirely.

"reconnecting…" in the terminal UICopy Anchor Link

The connection to the daemon dropped. The CLI reconnects on its own and catches up from the last event it saw. If the daemon was restarted, the session continues once it's back.

Sessions from the desktop app don't show up in the CLICopy Anchor Link

They use different data directories by default. Point the CLI at the app's daemon with --daemon-url and --daemon-token, or use the same --data-dir.

PermissionsCopy Anchor Link

The agent keeps asking for the same thingCopy Anchor Link

Choose Allow for this session or Always allow instead of Allow once. Always allow writes a rule to .cusp/settings.local.json. You can also switch to acceptEdits mode with Shift+Tab if the prompts are for file edits.

A command is denied in headless modeCopy Anchor Link

Headless runs can't prompt, so anything not pre-approved is denied. The JSON result lists each denial in permission_denials. Add the tool to --allowedTools, for example --allowedTools "Bash(npm test *)".

An allow rule doesn't seem to applyCopy Anchor Link

• Deny and ask rules win over allow rules. Check every settings file, including ~/.cusp/settings.json and managed settings.
• Compound commands need every part allowed. npm test && npm run lint needs rules for both.
• The workspace may not be trusted yet. Until it is, the project's own allow rules are ignored.
• In auto mode, very broad rules like Bash(*) are ignored on purpose.
• Writes to protected paths (.git, .cusp, .claude, shell startup files, …) always ask, whatever the rules say.

"plan mode: present a plan with ExitPlanMode first"Copy Anchor Link

The session is in plan mode, so edits and mutating commands are denied. Approve the agent's plan, or switch modes with Shift+Tab.

SandboxCopy Anchor Link

Commands fail with "Operation not permitted"Copy Anchor Link

The sandbox blocked something. Cusp tells the agent which limit was hit: a write outside the workspace, a read of a protected path, or network access. If the command legitimately needs it, add the path to sandbox.filesystem.allowWrite, open a local port with sandbox.network.allowLocalPorts, allow a host with sandbox.network.allowedDomains, or approve an unsandboxed run when the agent asks. Put these in your user settings (~/.cusp/settings.json); a project's own settings can't widen its sandbox.

"Sandbox unavailable"Copy Anchor Link

On Linux, install bubblewrap (sudo apt install bubblewrap or sudo dnf install bubblewrap). Some container environments don't allow the namespaces bubblewrap needs. Windows doesn't support the sandbox yet. Without a sandbox, shell commands are refused by default; to run them unsandboxed with permissions as the only layer, set "sandbox": { "failIfUnavailable": false } in your user settings.

Instructions and configurationCopy Anchor Link

My CLAUDE.md or CUSP.md isn't being followedCopy Anchor Link

• Check that it loaded: it should be in the project root or a parent directory of where you started. Files in subdirectories load only when the agent works there.
• Check claudeMdExcludes in your settings.
• Long instruction files get diluted. Keep the most important rules short and near the top, and move area-specific guidance to path-scoped rules.

A setting is ignoredCopy Anchor Link

Cusp drops invalid keys with a warning instead of rejecting the file. Run with --verbose to see warnings. Also check precedence: a value in .cusp/settings.local.json overrides .cusp/settings.json, and .cusp/ overrides .claude/ at the same level.

An MCP server's tools don't appearCopy Anchor Link

Project servers need approval before they connect. MCP tools are also deferred: the agent loads them by name when needed. See MCP servers.

Desktop appCopy Anchor Link

"Cusp is damaged and can't be opened" (macOS)Copy Anchor Link

The download was probably interrupted or modified. Delete the app and download it again from cusp.run/download.

The window is blank or the app shows "daemon failed"Copy Anchor Link

The daemon didn't start after several attempts. Choose Restart in the error view. If it fails again, check the logs in the app's log folder (on macOS, ~/Library/Logs/run.cusp.desktop/) and include them in a bug report.

Keys aren't saved on LinuxCopy Anchor Link

Cusp stores keys through the Secret Service API. Make sure a keyring (GNOME Keyring or KWallet) is installed and unlocked.

cusp:// links don't open the appCopy Anchor Link

On macOS the scheme is registered when the app is first opened from Applications. Open Cusp once, then try the link again.

Getting helpCopy Anchor Link

• Search or open an issue on GitHub.
• Write to support@cusp.run. The Support page lists billing and security contacts and the service status page.

Include the Cusp version (cusp --version), your operating system, the provider and model, and what you expected to happen. Don't include API keys or private code.