Troubleshooting
Diagnose connection, permission, and recovery problems.
The agent is offline
Check the process logs and GET /v1/health. Verify the control-plane URL, environment token, database URL, and outbound network access. A rotated token must also be updated in the agent's deployment secrets.
Connected, but records do not load
Your browser connects directly to the public agent URL. Test that URL from the user's network. Check its HTTPS certificate, reverse proxy, and public URL setting. A loopback or private hostname may work on the server but not on a teammate's laptop.
A field or action is missing
Confirm the project and environment, then check the user's role. A field may be hidden by read permissions; an action may be unavailable under the role or MCP scope. If a plugin action is missing for everyone, verify the plugin URL, signature secret, and plugin logs.
Notes cannot be opened
Notes need a live record-read check. Confirm that the agent is reachable and the user can still read the record. Self-hosted control-plane operators must explicitly allow trusted private agent origins using NOTES_AGENT_PRIVATE_ORIGINS.
Historical notes with no known environment are quarantined until an operator verifies and assigns their original environment. Do not assign them to production merely to make them visible.
AI requests are limited
Wait for in-flight requests to finish when concurrency is exhausted. Daily platform credits reset at midnight UTC. Workspace-owned provider keys can be used for decisions where configured; provider-side quotas still apply.
An operation may already have happened
Inspect the target system before retrying. See audit recovery and approval statuses. Repeated clicks can duplicate external side effects if the integration does not use idempotency.
Workspace deletion is pending
Deletion first records a durable intent, then cleans up billing and project resources. A failed external cleanup is retried and the workspace identifiers are retained. Resolve the underlying provider error rather than manually deleting the workspace row.