Troubleshooting

First checks

Is the app up? It answers on its health endpoint:

curl -s http://localhost:8080/api/health
# {"status":"ok"}

Read the logs of the app and of the runner:

docker compose --env-file .env.production ps
docker compose --env-file .env.production logs --tail 100 app
docker compose --env-file .env.production logs --tail 100 runner

The version running is shown at the bottom of the menu, from ORLOK_APP_IMAGE.

Installation

docker compose stops with "set ORLOK_SECRET_KEY" (or another variable). A required setting is empty in .env.production. See Environment variables.

The app does not start and its log says ORLOK_SECRET_KEY must be a base64-encoded 32-byte key. The key is not 32 bytes once decoded. Generate one with openssl rand -base64 32. On an existing installation, do not replace the key: put back the one it was installed with, or saved provider keys and credentials can no longer be decrypted.

The links in emails point to the wrong address. They use ORLOK_PUBLIC_URL. Set it to the address people actually open, the proxy's address when there is one, and restart the app.

Uploads fail with "You do not have permission to do this" behind a reverse proxy. Uploads must come from Orlok's own address. Set ORLOK_PUBLIC_URL to the address in the browser, and have the proxy forward X-Forwarded-Host and X-Forwarded-Proto. See HTTPS.

Signing in

"Too many login attempts. Try again in a few minutes." After 10 failed attempts on one account, or 50 from one address, sign-in pauses for up to 15 minutes. Wait, then try again.

The app returns to the sign-in page on its own. The session ended: it expired, it was signed out from another device, or an administrator disabled the person. The sign-in page says so: sign in again, and if that fails, ask an administrator whether your access is still active.

"This invitation is invalid, already used or expired." Invitations last 7 days and work once. An administrator can resend it from Admin → People.

The invitation email did not leave. The invitation is still created, and its link is shown at once so you can share it another way. Check Admin → Email and send a test email.

Colleagues

There is no + to create a colleague. The person has no colleague profile yet. The side list says whom to ask: an administrator grants profiles in Admin → People, administrators included.

"This colleague needs another profile." An administrator took away the profile it used. Open the colleague's settings and choose another one: it does not switch by itself, even when only one is left.

"The conversation no longer fits the model's window, even summarized." Start a new conversation, or use a profile whose model has a larger window.

"The model provider returned an error." Check the provider in Admin → Models: the key, the address, and whether the model still exists. Try it in the playground.

Operations

The runner shows as "Unreachable" or "Not configured" in Admin → Operations. "Not configured" means the app has no ORLOK_RUNNER_URL and ORLOK_RUNNER_TOKEN: with the package, check that the runner service is in compose.yaml. "Unreachable" means it is configured but does not answer: check docker compose ps and the runner's log, and that both containers have the same ORLOK_RUNNER_TOKEN.

A credential test fails.

Message	What to do
authentication failed	Check the username, password or key on the server itself.
the server cannot be reached	Check the host's address and port in Admin → Hosts, and that the runner can reach it: firewall, SSH service, on Windows the OpenSSH server.
the server host key changed	The machine presents a different key from the one Orlok trusts. If the server was reinstalled, an administrator uses Forget host key on the host. Otherwise, find out why before connecting.
the credential needs a username and a password or SSH key	Complete the credential.

A colleague says it cannot work on a server. You have no credential for that host, or the host is disabled. Add your own credential in Account → Credentials.

Every command asks for approval, and "Always allow" is missing. The command cannot be read to the end (a script, bash -c, a PowerShell line with variables), it reads a sensitive file, or an administrator turned its type off for you. See Modes.

A command was refused without asking. It is on the short list of catastrophic commands, refused in ask and full access. See Modes.

Wiki

Emptying a wiki fails with "A document is being read into the wiki: wait for it to finish, then try again." A wiki cannot be emptied while a document is being read into it. Wait for the import to finish, then empty it again.

"The page was changed by someone else in the meantime." Someone saved the page while you were editing it. Copy your changes, reload the page and apply them again.