First, the overall picture from the installation directory:
./draften status # version, health of both web colours and the workers, HTTPS, database dumps
Then in more detail:
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 |
| "The organisation has no Microsoft 365 or Google client set up" when connecting a mailbox with its account | the organisation has no client in the Account sign-in and mailbox connections card | an owner of the organisation adds one — see Microsoft 365 or Google Workspace, organisation client |
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 |
| the sample in the wizard says too little data | the owner used to reply from another address (say, before a domain change), and the wizard does not count those replies as theirs | add the address to the Other addresses of the mailbox field (by the sample, in the Period step, or on the mailbox page) and pick the sample again; the full address, not just the domain |
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 |
| the bar "The licence expired" or "The installation has no licence", the assistants write nothing | the licence is missing or has expired | upload a valid licence — see The licence |
the web service is briefly unavailable and requests in progress are lost; the web log (docker compose logs web-blue web-green) shows a restart | a request exceeded PHP's hard memory limit (since PHP 8.5.12 twice the memory_limit) and PHP ended the whole web process | Docker starts the web service again by itself, usually within tens of seconds; when it keeps happening, find the request that exceeded the limit in the log |
| an update ended with an error | the new version did not become healthy; the previous one keeps serving | the error in Requests or in the output of ./draften update; ./draften status |
| the web returns 502 after a server restart | releases older than 30 October 2026 switched the web in a way that made Docker treat the proxy as stopped by hand, so Docker did not start it again after the machine restarted | in the installation directory, docker compose up -d --no-deps proxy; an update to the release of 30 October 2026 or newer fixes it for good |
| "The last daily backup failed" in the Database backups card | the database dump failed (the message is in the card); it is tried again an hour later | run ./draften backup and read the error; check the free disk space (df -h) and ./draften status |
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.
When you need our help
./draften diagnose
writes a file diagnose-<time>.tar.gz with the installation's status, versions, the configuration without secrets and the end of the logs. Send it to us.
Before you send the file, look inside: the logs may contain addresses and subjects of the mail processed. Nothing leaves the server by itself.