Troubleshooting

Check the licence before anything else. It is the one failure in this addon that leaves no trace on any screen.

Generation is licence-gated inside the addon rather than only at the admin routes, because the assistant is woken by the customer's own reply route — a core path that carries no licence gate of its own. When the check fails, the trigger returns before a session, a turn row or a budget read ever happens. The console still opens, the Overview is healthy, Provider tests green, and the customer's conversation simply sits there.

The only signal is one warning line in the backend log:

AI support is enabled but this install is not licensed for it; staying silent

If verification could not be run at all — the licence service unreachable, a proxy in the way, DNS — you get the other line instead, and the outcome is identical:

License verification failed (<message>); staying silent

Both are AI_SUPPORT warnings. Grep the log for staying silent.

That second case is a fault, not a configuration, and the gate is deliberately fail-closed: an install that cannot prove it is licensed does not answer. The alternative would let an unlicensed install spend an operator's provider budget. Renew or re-activate the addon on Admin → System → Extensions, or restore the box's outbound access, then send a test message — nothing is queued, so the next customer message is the retry.

Almost always the knowledge base rather than a fault.

The shipped documentation describes the software. It says nothing about your fees, your limits, your countries or your timings — which is what tickets are about — and the assistant will not invent them. A correctly-built assistant on a fresh install escalates nearly everything.

Open Knowledge → Sources and answer the seeded questions in the banner. Then check Gaps: the list is your customers telling you exactly what to write.

If it escalates even on topics you have documented, use the retrieval tester on the same screen. It will show whether the article was found and, if so, how close it came to the floor.

Check prompt-cache health on the Overview screen first.

When the cache stops being reused, the cost per answer multiplies several times over with no error, no failed request and no log line. The reuse ratio on that screen is the only detection mechanism there is — nothing else on the platform will tell you.

If the ratio is healthy and the bill still rose, both usual causes are on Settings → Model: the answering model was changed, or the rerank and classifier models were pointed at a larger tier instead of the small fast one. Those two run on reranking, triage and the handover brief — several calls per conversation that nobody reads directly — so raising them moves the bill further than raising the answering model does.

You reached a budget ceiling. The daily one defaults to $5, which is deliberately low enough to be safe on an install nobody is watching, and it is not a number you should leave in production.

Reaching a ceiling is not a degraded mode — every conversation goes to a person until the window rolls over. Raise the ceiling on Settings, and check the Overview screen's remaining-budget figure regularly.

Remember that your own questions spend the same allowance. The admin assistant, the Handbook, Ask about this customer, Teach from this ticket and Test connection each make a real, billed call and each records it, so they count towards the same two ceilings a customer's answer does.

Not a budget that ran out — a budget that cannot be measured.

If a ceiling is set and any model call this month recorded no cost, the gate refuses with unpriced_model rather than assuming those calls were free, and the whole desk is notified with "AI support paused: spend cannot be measured". It is almost always the compatible-endpoint provider, which reports no cost unless you tell it what your endpoint charges.

Set AI_SUPPORT_OPENAI_INPUT_USD_PER_MTOK and AI_SUPPORT_OPENAI_OUTPUT_USD_PER_MTOK in .env and restart, or set both caps to 0 if the endpoint genuinely is free. Then release any conversation left parked — unlike the two budget reasons, this one is not lifted automatically when the cause is fixed.

Two different gates can do this, and they need different fixes.

If the retrieval tester shows the passage was found above the floor, the refusal came from the groundedness gate: the drafted answer had factual sentences that no citation covered. Support answers are mostly procedural prose, so a genuinely well-sourced answer can score lower than you would expect. Lower the groundedness floor on Settings, or make the article state the facts in citable sentences.

If the tester finds nothing, the article is not in the index. Re-index.

Re-index from Knowledge → Sources.

Settings survive an update; the knowledge index does not always. An index built from the previous release looks completely healthy and confidently describes screens that have moved — which is the worst version of this failure, because nothing appears wrong.

The backend reads .env at boot. If you edited the file and did not restart, the test is reporting the old state, which is indistinguishable from a bad key. Restart the backend, then test again.

If it still fails, read which step failed rather than the summary line. The test reports a tick or a cross per step with a sentence of detail underneath, and the steps fail for completely different reasons:

• The credential step failed — labelled Gateway credentials, API key or Endpoint depending on the provider. The variable is not set, or the backend has not restarted since you set it. The detail names the missing variable.
• Account failed (managed connection only) — the gateway is unreachable, or the credentials were refused by it. The same step reports your plan, balance and remaining cap when it passes, so an empty gateway wallet shows up here rather than as a mysterious generation failure.
• Answering failed — everything before it is fine and the model still did not produce a reply. The detail carries the upstream message: a rejected key, an exhausted balance, a refused connection or a timeout.

A cross on Answering under two ticks is the state a single "Connected" used to hide.

You are running without an agent record. The fallback persona is a nameless "Assistant" with no persona and no disclosure line.

Open Configuration → Agents and press Create default agent. If a row already exists, check it is active and that its disclosure line is populated — only the oldest active agent ever answers, so an edited second row changes nothing.

Three switches have to agree, and they are on two screens:

1. The tier switch for actions or processes — on Actions, off by default
2. The specific item ticked — on Actions, empty by default
3. Account tools — on Settings, Super-Admin only, the master cut-off

Walkthroughs work in the opposite direction: the tier is on by default and an empty list means all of them.

You included a key your role may not write. The screen saves as one batch, and a refused key refuses the whole payload rather than dropping the offender.

The twelve Super-Admin-only keys are greyed for anyone else precisely so this cannot happen, and what the screen greys is derived from what the route refuses, so the two cannot drift apart. If you hit it anyway, you are looking at a stale page — reload and try again.