FAQ

Install and start

deploy.sh fails, docker compose up says required variable … is missing A required .env entry is absent. deploy.sh generates them all; for manual installs check the configuration reference, especially RST_USER_DB_PASSWORD and CADDY_SITE_ADDRESS.

https://<hostname>/v2/ does not open docker compose -f docker-compose.prod.yml logs caddy gateway. Usually 443 is closed (cloud security group) or CADDY_SITE_ADDRESS is a bare IP (TLS handshake fails - use a hostname + hosts entry).

readyz shows es: ping or es_write: denied The first cannot reach ES (URL / certificate / network); the second lacks create / write on .rst_copilot_*. See ES permissions.

Gateway log: /app/state is not writable by uid 10001 An older state volume owned by root. docker run --rm -v <volume>:/s alpine chown -R 10001:10001 /s, restart the gateway.

Sign-in

"This deployment still uses the shipped default password, so remote sign-in is refused" RST_ADMIN_PASSWORD_HASH is unset. deploy.sh sets it; for manual installs see Installing from the archive. Isolated labs may set RST_ALLOW_DEFAULT_PASSWORD=1.

RST_ADMIN_PASSWORD_HASH is set but sign-in still fails Compose ate the $ in the hash. Write every $ as $$ in .env.

Users page says accounts cannot be added RST_USER_DB_URL is unset. deploy.sh configures it and starts userdb; for manual installs see Users.

Changed a role / disabled an account, the person is still working Disabling kicks sessions immediately; a role change applies immediately but does not kick. A page refresh shows it.

Smart query

Errors or empty results Read the card first; it usually already gives the cause: wrong time window (an "Ask for … instead" button), a blocking clause ("dropping X leaves N hits"), wrong index ("hits elsewhere"). Then: is the index whitelisted, are the model key / endpoint right.

"Index X is not in the configured whitelist" Add the pattern under Settings or ask an administrator.

"today / yesterday" returns nothing or the wrong day RST_TIMEZONE is unset and the gateway cuts days at UTC. Set your offset, e.g. +08:00.

First-token timeout, nothing for 45 seconds Endpoint congestion or a thinking model reasoning too long. Under AI models set that provider's reasoning to Off or Low, or add a fallback provider. RST_LLM_FIRST_TOKEN_TIMEOUT_S adjusts the cap.

The same question gives a different answer the second time Follow-ups in one conversation carry the previous turn's context (index, references). For a clean re-ask, click "+" for a new conversation.

Licence

"activation limit reached" Every host seat on this licence is used. Deactivate on the old host, then activate.

"Offline license is bound to a different host" The fingerprint in the .lic does not match: state/machine-id / state/server_guid were regenerated, or the file was issued for another host.

"no hardware identifier available" The container cannot read /etc/machine-id: state/machine-id is not mounted (a missing file makes docker mount a directory) or is not mode 644.

Activated, but the four paid features are still locked Online: wait for the first successful heartbeat (within 5 minutes); check "last heartbeat" on Activation. Offline: licences issued before 1.1.20 lack the three newer engines' keys; re-issue.

State "grace period" / "heartbeat lost" The gateway cannot reach license.reallysec.com:443. Check outbound access; after the grace period the licence expires.

Alerts and triage

Live alerts stays at 0 No new alerts in the index RST_ALERT_INGEST_INDEX points at, or ES_USER lacks read on .alerts-security.alerts-*. Search the gateway log for alert_ingest.

Batch triage: "AI scoring did not complete" Model timeout. Lower "clusters sent to the model" (10 works) or raise the provider timeout.

Triage pulls only a few alerts The default window is 60 minutes. Raise it (up to 7 days = 10080).

Knowledge base

Runbooks page says it is not enabled No embedding model. Test and save one under AI models → Knowledge-base embedding model.

Saving the embedding model is refused with a dimension mismatch The model changed. Delete the .rst_copilot_kb index, rebuild, re-upload.

Notifications

Email destination stays "retrying" / "given up" Read the last error in the delivery log. Usually no mail server configured, wrong password, or the SMTP port is blocked. Fix, then "Resend".

Feishu destination marked "secret stale" After a gateway reinstall the old ciphertext cannot be opened. Edit the destination and re-enter the webhook and secret.

Upgrades

Reports show "legacy format" after an upgrade Old structure; regenerate.

Something broke after an update ./deploy/rst-update.sh --rollback, or set GATEWAY_IMAGE_TAG back to the previous version and restart.

Still stuck

docker compose -f docker-compose.prod.yml logs --since 30m gateway > gateway.log and send it with the readyz output to support@reallysec.com. The log contains neither your log data nor secrets.