# Troubleshooting

First, three commands from the installation's directory:

```
docker compose ps                        # are the services up, is the database healthy?
docker compose logs --tail 50 worker     # the worker's last entries
docker compose run --rm worker node diag.mjs mailbox@company.com
```

The last one does the same as **Test the connection** in the interface: it
takes the access stored for the mailbox, acquires a token, prints its
permissions (never the token itself) and reads the inbox.

## Common errors

| Symptom | Cause | What to do |
|---|---|---|
| `set DB_PASSWORD in .env` at start | database passwords missing | fill in `.env` |
| `mailbox … has no access yet` | the mailbox has no registration or connected account | the mailbox's page → Mail access |
| `Graph … 401 … invalid_client` | wrong or expired client secret | a new secret at the registration, then the connection test |
| `Graph … 403 … AppOnly AccessPolicy` | the application access policy has not taken effect yet, or the mailbox is not in the group | wait (hours, even), repeat the test; add the mailbox to the group |
| `Graph … 403 … ErrorAccessDenied` | admin consent missing | in Entra, Grant admin consent at the registration |
| `Category not added … MailboxSettings` | the `MailboxSettings.ReadWrite` permission is missing; the label works, only without colour | add the permission and consent |
| `No active assistant in the database` | the assistant is switched off, or the initial data were not set up | switch the assistant on; check the start log |
| the assistant is skipped ("no prompts yet") | the assistant has no instructions written | finish the wizard, or write the instructions by hand |
| `Draft without signature` / `links outside the allowed domains` | the draft failed a check | look at the message — it may be a spoof attempt |
| `Limit reached` | the daily or per-sender limit | raise it only when the flood of mail is legitimate |
| `Model refused to answer` | the model's safety filter | handle the message by hand |
| `Model exhausted max_iterations` | the model looped in its tools | retried twice; when it keeps coming, tune the Task instruction |
| `ECONNREFUSED … 3306` | the database is down or not up yet | `docker compose ps`, `docker compose logs db` |

## When the log does not show it

- The interface: the assistant's Settings → **Activity** (mail checks,
  requests, events) and the **Operations** page (workers, queue, errors in 24
  hours).
- After three unsuccessful attempts a message gets the **failed** status; the
  last error is in its detail.

## A one-off pass by hand

```
docker compose run --rm worker node worker.mjs --dry-run
```

It takes every active assistant once and forces trial mode — nothing is
written into the mail. Useful to check that everything works.