Troubleshooting, by symptom

Find your symptom; follow the link to the page that owns the fix.

The stack won't cooperate

Which restart is safe, and what each one costs: the on-call runbook.

Symptom	First move
The hub won't start, or 500s everywhere	`curl -s http://localhost:8080/q/health` (no `lm` command reads it), then the hub logs
`required variable LUMNIK_SECRET_MASTER_KEY is missing a value` when the stack starts	the key is missing from `.env` — on a fresh install, generate one with `openssl rand -base64 32`; on an existing one, restore it from your backup (the master key)
`lumnik.secret.master-key is too short (< 16 chars)` at boot	the key is shorter than 16 characters — same fix
First boot seems stuck	migrations run at first boot — give it a minute, watch `./deploy/selfhost/logs.sh hub`
`up.sh` refuses to start, naming missing tools	its preflight — the message shows the exact install line; run it, re-run `up.sh` (Windows walkthrough, step 3)
`!! could not obtain a Keycloak admin token (check KEYCLOAK_ADMIN / KEYCLOAK_ADMIN_PASSWORD in .env)` at the end of `up.sh` — then logins fail	either Keycloak was still starting: re-run `up.sh`; or `KEYCLOAK_ADMIN_PASSWORD` in `.env` no longer matches the console's: set the same value in both. Still failing: `./deploy/selfhost/logs.sh keycloak`
Anything on a Windows PC	the dedicated page: Deploy on Windows → Troubleshooting
https / certificate trouble	the TLS proxy — caddy logs, Deploy

Symptom	First move
`401` with `tenant_id`, `subject/issuer` or claim errors	the claim wiring — BYO IdP troubleshooting has the full table
`403` on every endpoint despite a valid login	the `groups` claim doesn't carry `lm_*` role names — BYO IdP
`403 {"error":"user is deactivated"}`	the identity was archived (SCIM departure) — SCIM
Login broke after moving to TLS or a new hostname	the issuer changed — Keep the same public address
SCIM calls misbehave	SCIM troubleshooting — the issuer-mismatch `404` is the classic
`lm` prints `API error 403 (forbidden): no details from the server — your account may lack the required role` (raw HTTP: `403` with an empty body)	a required role is missing — Roles & permissions
`API error 403: missing role lm_integrator`	the `/api/platform/*` gate: the account lacks `lm_integrator` — same page

Symptom	What it is
`access refused (403): scope not granted` (raw HTTP: `403 {"error":"scope not granted"}`)	the business-scope boundary: your user holds scope roles and this resource is outside them. It covers every read surface (PWA lists, chat, views), so several going quiet at once points here. Scopes
The chat says "I can't answer that…" or "I won't run this…"	a guard refused rather than guess; the message says what to do next
"The query returned no rows. That can mean…"	an empty result — check the SQL shown before concluding there are none
`Error: API error 409: no schema discovered for scope '…' — apply an entity or run discovery first`	nothing was applied to the scope yet, or its last connector was deleted or moved — apply an entity (the message says so), then ask again
The ask answers "I have no data declared for this scope yet…" although you ingested into that scope	the scope's schema card declares no tables — see below
`429` on chat, search, or view-generate — not a connector run	the hub's own inbound limit — Rate limits. A vendor throttling a connector is the `429` under Ingestion

Look at the scope's schema card (needs lm_admin on top of lm_integrator):

`lm source schema --scope <scope>` prints	Meaning	Fix
`(no tables — run 'lm source rediscover --scope <scope>')`	the card exists but declares no tables	run that `lm source rediscover`; it removes the empty card
`Error: API error 404: No schema card found for scope: <scope>`	no card at all — the `409` state above	apply an entity to the scope

The ask is Pro only; lm source schema and rediscover exist on both editions.

Symptom	First move
The ask/chat errors after ~20 s, with an opaque error id	the model failed to load on the machine running Ollama — on Windows, update the NVIDIA drivers first, then the RAM note: Deploy on Windows, step 5
The very first ask after a restart is slow or times out	the model loads on first use (tens of seconds on CPU) — ask again; on a server set `OLLAMA_KEEP_ALIVE=-1` in Ollama's own environment (Deploy)
Chat/search return nothing, ask has no model	Ollama isn't installed or reachable — install it (Windows: step 5) and check `OLLAMA_BASE_URL` (Models)
Same, on a Linux host	Ollama listens on `127.0.0.1`, which the hub container cannot reach — bind it on the Docker bridge: Deploy → Linux host

Symptom	First move
A run failed, or rows are missing	the dedicated recipe: Diagnosing a failed run
`run scheduled` looked fine, but `lm run list` says Failed	"scheduled" only means queued. Failed at 0/0 usually means the source did not answer — `lm run get <id>` prints why (Diagnosing a failed run)
A run says Completed but `IN=0 OUT=0`	the connector found nothing to read — for file connectors, the path or mount does not exist where the hub looks (the WOW's ✔ checks catch it)
`lm entity apply` errors naming a relation that `does not exist`	a source connector never landed rows — check `lm run list`
An applied entity never shows up in `lm ask`/chat	the manifest declares no `scopes:` — Entities troubleshooting
`429 Too Many Requests` from a REST vendor	lower `default_rate_limit` — REST troubleshooting
SFTP auth, host-key, or S3 `403` errors	CSV & files troubleshooting
`Bearer token unavailable (env=…)` — REST connectors only	the secret was never set — `lm secret set`, quickstart table
jdbc run fails: `password_env '<NAME>' is neither in the server environment nor in lm secret`	`lm secret set <NAME>`, or set it in the hub's environment — JDBC troubleshooting
A cursor seems stuck in the past	`lm endpoint reset-cursor <connector>/<endpoint>` — next run is a full refresh

Symptom	First move
A webhook never arrived	`lm outputs list` (failures first), then `lm outputs replay <ID>` — or `^R` in the TUI `:outputs` (Outputs)
The Records list on a phone looks empty	see the table below
The PWA shows an old version after a hub upgrade	the phone keeps the app's screens between openings (offline). Close the app and open it again, twice if needed: a new version is fetched at one opening and shown at the next
`lm view -f v.yaml` (the list), `lm view KEY -f v.yaml` (one record) or `lm view apply` refused	a manifest field/column mismatch, or a missing scope role — Views troubleshooting
`lm process apply` refused, or a declared process never fires	a manifest/schema mismatch, or its trigger table broke at runtime — Processes troubleshooting
`lm workflow apply` refused	an unknown field, a lifecycle collision, or dormancy declared without `on.key` — Workflows troubleshooting
A workflow alert didn't fire	dormancy is observation-relative and needs `on.key` + `dormancy.after` — Workflows

An empty Records list on the phone:

You see	Meaning	Where to look
an amber box with a message	a refusal, with its reason: no view applied for the scope, or `403 scope not granted`	Views troubleshooting, Scopes
grey "Aucune ligne" text	the view rendered and found zero rows	the source data

Still stuck? Reading the logs says where every component writes, and how to raise the volume for the minutes you need it.