Troubleshooting
Diagnose connection, permission, and recovery problems.
The connector 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 connector's deployment secrets.
Connected, but records do not load
Your browser connects directly to the public connector 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.
The back-office says the connector did not respond while the connector looks healthy
The address the dashboard holds is wrong, not the connector. Without AVIATO_PUBLIC_URL, the connector advertises http://localhost:<port>, the dashboard hands that address to the browser, and the request never leaves the laptop. Check the connector's startup logs for the loopback warning.
A blank value is read as missing, so this is easy to hit with deployment variable references: on Railway, https://${{RAILWAY_PUBLIC_DOMAIN}} resolves to nothing until a domain is generated for the service. Generate the domain, set the variable and restart. The control plane stores the URL the connector reports on every heartbeat, so a stored localhost address is corrected within seconds and needs no intervention.
A development environment does not load or start
A development environment's connector runs on its owner's computer, so the dashboard reaches it at http://localhost:<port>: check that aviato dev is running there, and allow local network access if the browser asks. If the connector stops with "Your development environment was removed or its credential replaced", the environment was removed or approved again on another computer; run the command again to approve this one. With --tunnel, a closed tunnel is reported in the terminal; restart the command for a new address, and give MCP clients the new URL.
The connector stops with AVIATO_DATA_DIR … cannot be written
The connector keeps the audit outbox, the decision cache, the approval journal and the upload registry as SQLite files in its data directory, and checks that it can write there before anything else. The image normally handles this itself: it starts as root, gives the directory to uid 65532 and continues as that user, so a volume mounted as root needs no preparation.
What is left are the cases where it cannot. A container pinned to a user (docker run --user, a securityContext, AVIATO_RUN_UID) keeps that user, so the mount has to belong to it. A read-only mount is writable by nobody. On a mount that refuses to change owner, such as NFS or SMB, the connector warns and stays root rather than dropping into a directory it could not write. Connectors before 0.2.3 report all of this as unable to open database file.
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 through GET /v1/collections/{collection}/records/{id}/access. Upgrade connectors before the control plane so this endpoint is available; it returns no record data and does not run computed fields. Confirm that the connector is reachable and the user can still read the record. Self-hosted control-plane operators must explicitly allow trusted private connector origins using NOTES_CONNECTOR_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.
SSO roles after upgrading an existing installation
Group-based role changes now record the previous role so a later sign-in can restore it when the mapped group is removed. Memberships created before this tracking was introduced have no reliable history of whether their role came from SSO or a manual assignment. Review existing elevated memberships against your identity provider and explicitly correct their roles; the migration cannot reconstruct that history. SCIM-managed memberships continue to follow SCIM provisioning.
Ask your data cannot load a schema
Ask your data retrieves the schema from the live connector using your current permissions. An offline or unreachable connector prevents generation. The NOTES_CONNECTOR_PRIVATE_ORIGINS operator allowlist also applies to this connection when the connector has a private address. Hidden collections and fields are not sent to the language model.
AI requests are limited
Wait for in-flight requests to finish when concurrency is exhausted. Daily platform credits reset at midnight UTC. Workspace-owned OpenRouter keys can be used for Clef decisions where configured; provider-side quotas still apply. Clef also rejects requests whose serialized state and questions exceed 2,000 UTF-8 bytes. Select fewer input fields or shorten their content. See Data flow and privacy for model configuration and fallback behavior.
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 removes the workspace's SSO identity providers and 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.
Checkout is already being prepared
Another checkout request holds a short reservation for this workspace. Wait and retry with the same plan and billing interval. The control plane retains the original Stripe parameters and idempotency key, so changing a price or user profile during recovery does not create a different request.
If a checkout says its outcome requires reconciliation, contact the control-plane operator. Automated retries stop before Stripe's 24-hour idempotency retention window can expire. Reusing an old key after Stripe discards it could create another session.
For self-hosted operators, inspect the workspace's workspace_checkout row and the Stripe account before changing recovery state. Match the operation ID to Checkout session metadata aviato_operation, and the workspace ID to customer metadata workspace_id. If a subscription exists, synchronize the billing mirror and use the billing portal. If an open session exists, recover or expire it before clearing the reservation. Only clear an unresolved reservation after confirming that no live session or subscription remains. Keep the operation ID in your incident record; do not simply change its creation timestamp to bypass the recovery window.