For administrators
← All topics

Troubleshooting

Symptom, cause and what to do — from missing mailbox access to an expired secret.

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

SymptomCauseWhat to do
set DB_PASSWORD in .env at startdatabase passwords missingfill in .env
mailbox … has no access yetthe mailbox has no registration or connected accountthe mailbox's page → Mail access
"The organisation has no Microsoft 365 or Google client set up" when connecting a mailbox with its accountthe organisation has no client in the Account sign-in and mailbox connections cardan owner of the organisation adds one — see Microsoft 365 or Google Workspace, organisation client
Graph … 401 … invalid_clientwrong or expired client secreta new secret at the registration, then the connection test
Graph … 403 … AppOnly AccessPolicythe application access policy has not taken effect yet, or the mailbox is not in the groupwait (hours, even), repeat the test; add the mailbox to the group
Graph … 403 … ErrorAccessDeniedadmin consent missingin Entra, Grant admin consent at the registration
Category not added … MailboxSettingsthe MailboxSettings.ReadWrite permission is missing; the label works, only without colouradd the permission and consent
No active assistant in the databasethe assistant is switched off, or the initial data were not set upswitch the assistant on; check the start log
the assistant is skipped ("no prompts yet")the assistant has no instructions writtenfinish the wizard, or write the instructions by hand
the sample in the wizard says too little datathe owner used to reply from another address (say, before a domain change), and the wizard does not count those replies as theirsadd 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 domainsthe draft failed a checklook at the message — it may be a spoof attempt
Limit reachedthe daily or per-sender limitraise it only when the flood of mail is legitimate
Model refused to answerthe model's safety filterhandle the message by hand
Model exhausted max_iterationsthe model looped in its toolsretried twice; when it keeps coming, tune the Task instruction
ECONNREFUSED … 3306the database is down or not up yetdocker compose ps, docker compose logs db
the bar "The licence expired" or "The installation has no licence", the assistants write nothingthe licence is missing or has expiredupload 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 restarta request exceeded PHP's hard memory limit (since PHP 8.5.12 twice the memory_limit) and PHP ended the whole web processDocker 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 errorthe new version did not become healthy; the previous one keeps servingthe error in Requests or in the output of ./draften update; ./draften status
the web returns 502 after a server restartreleases 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 restartedin 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 cardthe database dump failed (the message is in the card); it is tried again an hour laterrun ./draften backup and read the error; check the free disk space (df -h) and ./draften status

When the log does not show it

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.

Plain text version