# Troubleshooting (https://docs.getaviato.com/administration/troubleshooting)



## The agent is offline [#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 [#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 [#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-cannot-be-opened]

Notes need a live record-read check through `GET /v1/collections/{collection}/records/{id}/access`. Upgrade agents before the control plane so this endpoint is available; it returns no record data and does not run computed fields. 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.

## SSO roles after upgrading an existing installation [#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-cannot-load-a-schema]

Ask your data retrieves the schema from the live agent using your current permissions. An offline or unreachable agent prevents generation. The `NOTES_AGENT_PRIVATE_ORIGINS` operator allowlist also applies to this connection when the agent has a private address. Hidden collections and fields are not sent to the language model.

## AI requests are limited [#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 [#an-operation-may-already-have-happened]

Inspect the target system before retrying. See [audit recovery](/administration/audit) and [approval statuses](/guides/actions). Repeated clicks can duplicate external side effects if the integration does not use idempotency.

## Workspace deletion is pending [#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.

## Checkout is already being prepared [#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.