Troubleshooting
For whoever is running the desk. The symptoms people actually report, and what they usually are.
Nothing is being emailed
In this order:
- Is a worker running?
supervisorctl status. No worker, no mail, every message is a queued job. - Is the scheduler firing?
/etc/cron.d/, and check the user in that file can run PHP. - Is the mode still “log”? Settings → Email. A fresh install writes mail to a file on purpose.
- Is the queue backed up? Settings → Health, then Logs → System for the per-job summary.
- Is the relay refusing? Logs → Email shows the state per message and the failure reason.
A new agent sees nothing at all
They belong to no brand or no department. That is the whole answer nine times in ten, and it looks exactly like a broken install. Staff → their page → Brands and departments.
Client replies are opening new tickets instead of threading
- The mailbox is reading an address the desk does not send from, so replies carry no token.
- Or the ticket emails predate the mailbox being connected: a brand only adds the reply token and the “reply above this line” marker once it reads a mailbox.
- Or the client’s provider strips the sub-addressed Reply-To, switch that mailbox to putting the token in the subject.
Logs → Email → the inbound tab shows the outcome and the reason for each message.
A mailbox has stopped
Administrators are alerted after fifteen minutes, and the brand card warns. Usually an expired OAuth consent (sign in again on the mailbox page) or a changed password. Test the connection from the mailbox’s own page; it says what failed.
The chat widget does not appear
- The site’s origin is not on the brand’s allowed origins list.
- Or chat is paused, or the department is outside its opening hours with no offline form.
- Or the page is behind a privacy blocker that matched the old
/chat/path; the current loader is/w/.
GET /w/{key}.js in a browser tells you quickly: a 404 means the key is wrong or chat is off.
Everybody was signed out at once
The queue, cache or session driver changed, moving sessions from the database to Valkey signs everyone
out once, by design. If nobody changed anything, check the application key: a redeployed .env with a
new APP_KEY invalidates every session and makes encrypted settings unreadable. Restore the original
key.
The desk shows old behaviour after a deploy
PHP-FPM was not reloaded. With opcache.validate_timestamps=0 the old code keeps running until it is.
systemctl reload php-fpm, and add it to your deploy script.
If it is the front end that looks stale, it is a cached bundle: hard refresh.
Attachments are refused
The brand’s file rules decide. The refusal names exactly what would have been accepted. If it is a size complaint at the server rather than the form, PHP is narrower than the brand’s setting, the Files panel says so per group.
A file refused as “not what its name says” is a program wearing another extension. That check is not a setting.
Search is slow
It should not be, word searches use full-text indexes. If one particular search is slow it will be a word under three characters or something containing symbols (an IP, an email address), which cannot use a word index. See Searching.
The AI does nothing
- The brand’s master AI switch is off, or there is no key chosen for that use (drafts, summaries and triage are chosen separately).
- Or the per-agent “AI on tickets” permission is not ticked.
- Or a daily cap has been reached, Logs → AI shows the runs and the reason.
Visitors: I am not in the list
By design: any address the staff app has been used from in the last 24 hours is left out of visitor figures. Settings → Location and visitors → “Leave out staff”. Excluded sessions still show in “Visitors now”, marked.
Reports are not visible to a colleague
A report is visible to whoever can see the project its type points at. A security type pointed at a members-only project is invisible to everyone not named on that project, which is the intended behaviour, and worth checking before assuming a bug.
A rule did nothing
Open the rule and look at its runs: shadow mode logs what it would have done, the per-rule brake caps runs an hour, and repeated failures pause a rule automatically with an alert. The conditions panel also has a backtest against recent tickets.
The queue heartbeat is red but the workers are running
The workers are running old code, or they are all busy on one slow job type. Restart gracefully from Settings → Health, then look at Logs → System for the per-job 24-hour summary.
Where to look, in general
| Question | Place |
|---|---|
| Who changed this ticket? | Logs → Activity |
| Did that email go? | Logs → Email |
| Why did that message not become a reply? | Logs → Email, inbound tab |
| Who signed in, and how? | Logs → Security |
| Who revealed a credential or exported a conversation? | Logs → Access |
| Why did that rule fire? | Logs → Rules |
| Is the desk healthy? | Settings → Health |
| What did the crawler do last night? | Logs → Knowledge |