Skip to main content

​
Start here

These four commands identify most problems:

​
Installation

The environment schema is validated at startup, so a missing or invalid value stops the process immediately.
Common causes:
  • BETTER_AUTH_SECRET or SETTINGS_ENCRYPTION_KEY shorter than 32 characters
  • BASE_URL not a valid absolute URL
  • DATABASE_URL missing or malformed
Migrations cannot reach the database. Confirm the database pod is ready and the connection string resolves:
With the bundled database, the password inside DATABASE_URL must match POSTGRES_PASSWORD in the same Secret.
The application is up but the database query failed. Check credentials, connection limits, and whether the database pod restarted.
The storage class is missing or cannot provision ReadWriteOnce volumes.
Confirm the ingress class matches your controller, DNS points at it, and the Service has endpoints:

​
Authentication

The most common misconfiguration. publicUrl does not match the URL in the browser, so the session cookie is scoped to the wrong host and rejected. Align publicUrl, ingress.host, and DNS, including https:// versus http://.
The setup transaction did not complete. Check logs for a database error, and query the state:
The token must match SETUP_CLAIM_TOKEN in the running pod’s environment exactly. If you changed the Secret, restart the Deployment so it is re-read.
The provider’s registered redirect URI must be exactly https://<publicUrl-host>/api/auth/oauth2/callback/<provider-key>.
BETTER_AUTH_SECRET changed. Restore the original value to preserve sessions; otherwise users simply sign in again.

​
Workspaces

The pod missed the 90-second readiness window.
Usual causes are a slow first image pull, volume attach delays, exhausted quota, or a missing RuntimeClass when workspace.runtimeClassName is set.
workspace.imagePullSecret is not set. The control plane’s imagePullSecrets does not apply to workspace pods, so both must be configured for private images.
Either activity is genuinely ongoing, a lease is stuck above zero from a process that never finished, or the reconciler is erroring. Check control-plane logs and confirm WORKSPACE_IDLE_SECONDS.
The container hit its memory limit and was OOM-killed:
Raise workspace.resources.limits.memory.
Only /home/r5d persists. Anything installed into system paths is lost when the pod scales to zero. Add durable tooling to the workspace image instead.
Recoll indexes incrementally and may not have indexed recent files yet. Very new or unsupported formats also return no matches. Try grep for exact text.

​
Models and providers

The outbound guard blocked the URL. It must be HTTPS and publicly resolvable, unless ALLOW_PRIVATE_EGRESS or ALLOW_INSECURE_HTTP is enabled.
The stored API key is invalid or lacks model access. Keys are write-only; re-enter rather than trying to read it back.
The provider model ID must match the provider’s exact identifier, and the base URL should end at /v1 without repeating the version segment.
The configured context window exceeds the model’s real limit. Lower it to the documented value.
SETTINGS_ENCRYPTION_KEY no longer matches the one used to encrypt the data, usually after a restore. Restore the original key; otherwise credentials must be re-entered.
The application promotes the oldest enabled model automatically when a default is removed. If no enabled model exists, add or enable one.

​
Helm

GitHub Pages must be enabled for the repository and at least one release must have published an index.yaml. Verify directly:
The local cache is stale. Run helm repo update r5d-chat, then helm search repo r5d-chat --versions.
The package is private. Authenticate with a token that has read:packages:
With --atomic, Helm reverts automatically. Inspect why before retrying:

​
Collecting diagnostics

When reporting an issue, gather non-sensitive context:
Review the output before sharing it. helm get values can include credentials if you passed them through values instead of existingSecret.