> Something is wrong with your q15 stack. Match the symptom, then read what to do about it.

Start with the checks, not with the table:

```bash
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](/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](/reference/#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](/reference/)                                             |
| `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](/chat/)                               |
| `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](/chat/)             |
| 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](/chat/)                               |
| 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](/chat/)                    |
| 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](/chat/)                       |
| 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](/updating/)                                       |
| 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](/updating/)                                                     |
| 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](/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

```bash
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](https://github.com/q15co/q15/issues). Include the output of `q15 doctor` — it is written to be
pasted.
