Troubleshooting

Start with the checks, not with the table:

q15 doctor                          # what runs, which credentials resolve, what the agent can reach
q15 status                          # the containers, and the units behind them
q15 logs -f q15-agent               # follow the agent while you reproduce the problem

doctor names the check that fails. If it comes back clean and the stack still misbehaves, match the symptom below.

Not built yet. The q15 verbs above are the target state. Until the binary ships, the same three things come from Compose: podman compose … ps for status, … logs -f q15-agent for logs, and the health checks the stack runs on start. The exact commands are in the reference.

Symptom, cause, fix

Symptom	Likely cause	What to do
`up -d --wait` never returns	A health check is not passing: usually the model download, or one container crash-looping	Run `q15 status`, then `q15 logs` on the service that is not healthy
`q15-agent` exits at startup	Empty model roster: no reachable provider, or a missing or empty key file	Check the providers in the agent config and the matching files in `secrets/` — Configuration
`q15-tei` will not start on a VPS	The default image targets NVIDIA Turing GPUs and reserves a GPU	Switch to the CPU image and drop the GPU reservation — Compose
`q15-web` exits immediately	`Q15_WEB_ORIGIN` is not an exact HTTPS origin, or has a trailing slash	Set it to `https://your.host`, or `http://localhost:8080` for local use — q15-web
`q15-web` fails after you change the hostname	The credential store is bound to the original origin	Keep the original origin, or change it with `q15 origin set` and enrol every device again — q15-web
Enrolment is refused in the browser	The passkey is synced or backup-eligible, or verification was not required	Use a security key with a PIN, or a device-bound platform authenticator — q15-web
The enrolment command times out	The ceremony window is five minutes	Run `q15 auth enroll 'Laptop'` again and paste the response back inside the window — q15-web
Sockets close and you are asked to sign in again	The session expired, or the credential was revoked on the host	Sign in again; if a device was lost, enrol a replacement and revoke the old one — q15-web
Everything is signed out after a restore	The restored web state contains devices and sessions you had revoked	Revoke them again before exposing the service — Updates and rollbacks
The web tier logs a protocol mismatch	Agent and web images come from different releases	Move the whole stack to one tag — Updates and rollbacks
The Telegram bot does not reply	The user is not on the allow-list, or the token file is still the template	Fill both Telegram secret files in `secrets/` and restart the agent — Telegram
Embedding calls fail right after first start	The embedding model is still downloading	Wait, and watch `q15 logs -f q15-tei`

Reading the logs yourself

q15 logs -f q15-web              # substitute any service: q15-agent, q15-exec, q15-proxy, q15-tei, q15-qdrant

The web tier logs enrolment, sign-in, refusal, logout and revocation with device IDs, and never logs cookies, assertions, request bodies or chat content. Log rotation is the host’s job; q15 does not rotate your journal.

Where to report

If no row matches, open an issue on the q15 repository issue tracker. Include the output of q15 doctor — it is written to be pasted.