Skip to main content

Common Troubleshooting

First confirm the scope of the problem: is the web page not opening, is an administrator configuration incomplete, or did a single model request fail? The following order avoids repeatedly rebuilding containers while the application is actually healthy.

The web page won't open​

In the deployment directory, check container status and recent logs:

docker compose ps
docker compose logs --tail=200 app

Confirm the security group allows the application port, and that the reverse proxy's upstream points at the application container, not PostgreSQL, Redis, or Qdrant. The app and /api use the same origin, so the proxy doesn't need an extra front-end API address.

Requests return cross-site request blocked​

This is Aivory's origin check, not a browser CORS message. For a domain or HTTPS reverse proxy, set the exact browser origin in the deployment env file, for example ALLOWED_ORIGINS=https://chat.example.com, then restart app. Do not include /api, another path, or a trailing slash.

Can sign in but can't chat​

In the admin console, check in this order:

  1. The channel is enabled, and its Base URL, API key, and API format are correct.
  2. The channel has at least one enabled chat model.
  3. A default chat model is selected in the model policy.
  4. The upstream provider allows the current model, and the account still has available quota.

For OpenAI-compatible channels, the Base URL usually ends with /v1, but follow the provider's documentation for the exact path. Never put API keys into front-end build variables or public logs.

OAuth sign-in reports token_exchange_failed​

If the logs contain context deadline exceeded or github exchange failed, the application server usually timed out reaching GitHub's token endpoint, rather than the account linking record being corrupted. Check:

  • whether the server can resolve and reach github.com:443, plus the egress firewall, proxy, and DNS.
  • whether the callback URL in the GitHub OAuth App exactly matches the current public domain.
  • whether OAUTH_CALLBACK_BASE_URL, the client ID, and the client secret all belong to the same OAuth App.
  • whether the system time is accurate; clock skew makes state or cookie validation fail.

Start the sign-in again after fixing the network or configuration. Don't write the client secret into the browser, and don't forward one-time callback parameters to anyone else. If egress must go through a proxy, configure a standard HTTP(S) proxy in the application runtime environment and confirm the proxy allows GitHub's token requests.

Python interpreter shows as not configured​

The Personal edition does not deploy the sandbox by default. When the admin tools page shows "Please configure the sandbox first", you can:

  • enable the sandbox profile in the Personal edition Compose file; or
  • fill in a reachable SANDBOX_BASE_URL and matching SANDBOX_API_KEY.

Open the Python interpreter only after confirming the sandbox sidecar is healthy. Don't publish the sandbox port to the public network; the sidecar uses the Docker socket and should only be enabled on trusted hosts.

The knowledge base returns no results​

Confirm the documents have finished parsing and indexing, and that the dimension returned by the embedding model matches EMBEDDING_DIM. Full deployments should also check Qdrant health:

docker compose ps qdrant
docker compose logs --tail=100 qdrant

The Personal edition uses vectors embedded in SQLite and does not need Qdrant running. After changing the embedding model, rebuild the affected knowledge bases as prompted in the admin console.

ARM64 image pull failures​

Confirm the host is 64-bit ARM (uname -m usually shows aarch64) and use the latest release tag. Official multi-architecture tags are selected automatically by Docker; don't force a wrong platform in Compose. If you use an older self-built image, build and push a manifest for linux/amd64 and linux/arm64 separately.

Check whether the link was revoked by its owner, whether it exceeded the app's share policy time limit, and whether the reverse proxy forwards /api/public/shared/ and shared asset paths. Attachments in public snapshots still need the application's storage to be accessible; after migrating or cleaning up DATA_DIR, having only the database without the uploads/artifacts directories will break previews.

Collecting diagnostic information​

When filing an issue, include the Aivory version, deployment mode (Personal or Full edition), CPU architecture, the status of the relevant containers, and sanitized logs. Remove API keys, OAuth secrets, JWT secrets, share tokens, and user file contents; don't upload the full .env file directly.

Last updated on