Troubleshooting

This is the runbook for the issues that come up most often. Each section follows the same shape: symptom, likely cause, what to do. Start at System status before reaching for any of these, since most problems show up there first.

Sign-in fails for AD or LDAP users

Symptom: Directory users can't sign in. Local admin still works.

Likely cause: Service account credentials, directory connectivity, user filter, or TLS certificate.

What to do:

1. In the admin UI, open the directory integration and use the Test connection action. It binds with your service account and reports the exact error.
2. If the test fails on bind, your service account password has likely changed or expired. Reset it in your directory and update Stoa.
3. If the test succeeds but lookups return zero users, your search base or user filter is too narrow. Widen it and test with a known user.
4. If you use LDAPS, check the directory's TLS certificate and that its issuer is trusted by the host. An expired CA is a common quiet failure.
5. Check host-level connectivity to the directory (ports 389 or 636). A firewall change is the second most common cause.

See Active Directory.

Sign-in fails for local users

Symptom: A local (non-directory) user can't sign in.

Likely cause: Wrong password, the user is meant to be in AD, or their role no longer exists.

What to do:

1. Check whether the user is supposed to be a local account at all. In AD-backed deployments, local accounts are usually only for the break-glass admin.
2. Reset the password from the admin UI and have the user try again.
3. Check the user's assigned role. If it was deleted, the user can authenticate but can't do anything. Reassign a valid one. See Roles & permissions.
4. Check the audit log for failed sign-in entries. They include the reason.

KB ingestion stuck or failing

Symptom: A document sits in "processing" forever, or fails outright.

Likely cause: Disk full, the language model service degraded, or a malformed document.

What to do:

1. Check disk usage on System status. Above 90% and ingestion will fail.
2. Check whether the language model service is degraded. Ingestion uses it to produce embeddings, and an Office document (Word, Excel, PowerPoint) also passes through the document conversion service on its way in.
3. Check the audit log for the upload entry and any matching error.
4. Try re-uploading. Transient failures sometimes resolve on a fresh attempt.
5. If a specific document fails repeatedly, open it in its native application to rule out a corrupt file. Note that an encrypted PDF isn't automatically a lost cause: most "encrypted" PDFs you'll run into (a great many published reports, for instance) use an empty owner password and open without anyone typing anything, and Stoa reads those normally. A PDF that genuinely needs a password typed in to open still won't ingest.

If the language model service was unreachable when a document was ingested, the document doesn't fail outright: its text is still stored and searchable by keyword. Once the service is back, reindex the knowledge base (or use "Reindex all" from the admin UI) to fill in the embeddings that similarity search needs.

Slow chat responses

Symptom: Chats are noticeably slower than usual.

Likely cause: Language model service overloaded, GPU memory full, model not fully loaded, or you're past the concurrent-user ceiling for your hardware tier.

What to do:

1. Check GPU utilization and GPU memory on the host. GPU memory above 95% is a red flag.
2. Check the language model service's latency on System status. If it's elevated for everyone, that service is the bottleneck.
3. Check how many users are signed in. Each hardware tier has a realistic concurrent-user ceiling.
4. After a host reboot, the model takes a minute or two to load on the first request. Brief slowness right after a restart is expected.
5. If you've recently switched to a larger model, your GPU may not have the headroom. Roll back and verify, then plan an upgrade.

See Performance tuning for the longer-term levers.

Citations missing on answers that should have them

Symptom: A chat returns a real answer but no citations, even though the user expected the assistant to use a knowledge base.

Likely cause: The chat wasn't grounded in a KB. The model answered from its general training instead.

What to do:

1. Check whether the user is on an agent that's wired to the relevant KB. A general agent without KB tools won't cite anything.
2. Have the user rephrase the question to point at the KB explicitly, or switch to an agent that has the right KB attached.
3. If the agent does have the KB attached, confirm the KB was fully indexed. A KB still ingesting can return zero hits.

Webhooks not firing

Symptom: A webhook is configured but the destination never receives anything.

Likely cause: Wrong URL, wrong HMAC secret, destination unreachable from the host, or destination rejecting the payload.

What to do:

1. Webhooks are registered through the platform's API today, not a screen in the admin UI, so start with whoever set it up (your delivery engineer or your integration team) and ask them to trigger a synthetic test delivery. It reports the destination's response.
2. If the test fails with a network error, check that the host can reach the destination URL. Outbound firewall rules are the usual culprit.
3. If the test returns a 4xx, check the destination's logs. The HMAC signature is wrong, or the payload format isn't what the destination expects.
4. Confirm the secret on the destination matches the one stored in Stoa. Rotating one without the other is a common silent break.
5. Remember that a real delivery only ever fires once, with no retry. If the destination was briefly down when the event happened, that specific delivery is gone; cross-check the audit log for the underlying action instead of expecting a second attempt.

See Webhooks.

Email notifications not arriving

Symptom: Welcome emails or notifications aren't being delivered.

Likely cause: SMTP misconfiguration, spam filtering, or outbound network restriction.

What to do:

1. Open the SMTP integration and use the Send test email action.
2. If the test fails, check the host name, port, credentials, and TLS mode against your mail server's docs.
3. If the test succeeds but real emails don't arrive, check the recipient's spam folder. The from-address may need an SPF or DKIM record on your domain.
4. For air-gapped sites, check that the host can reach your internal mail relay. Outbound to ports 25 or 587 is often blocked by default.

See Email (SMTP).

Disk filling up

Symptom: System status shows disk above 80%.

Likely cause: Audit log growth, KB indexes, or unbounded conversation history.

What to do:

1. Identify which dataset is growing fastest. Usually KB indexes (if you've been ingesting) or the audit log (if you've been busy).
2. Take a backup before pruning anything. See Backups.
3. Adjust audit log retention if it's longer than your compliance policy requires.
4. Delete or archive KBs you no longer use.
5. If growth is steady, plan a storage expansion rather than pruning every few weeks.

A service shows "degraded" on System status

Symptom: One service card is yellow, the rest are green.

Likely cause: Brief load spike, a large in-flight request, or a real problem developing.

What to do:

1. Check the latency reading on the affected card. Mildly elevated and recovering is fine. Sustained and climbing is not.
2. Check whether the host is under load. CPU or memory above 90% explains most degraded states.
3. Wait 30 to 60 seconds and refresh. Brief degradation during heavy use is normal.
4. If it persists, check the audit log for any recent admin action that lines up with the time the status changed.
5. As a last resort, restart the affected service. Your delivery engineer can walk you through it the first time.

GPU not detected after a reboot

Symptom: After rebooting the host, the language model service won't start or starts in CPU-only mode.

Likely cause: GPU driver didn't load, the device isn't visible to the container runtime, or the container doesn't have GPU access.

What to do:

1. Check that the NVIDIA driver loaded on the host. The standard nvidia-smi command should list your GPU.
2. Check that your container runtime has GPU access enabled. After a kernel update, the NVIDIA container toolkit may need to be reinstalled to match.
3. Confirm the container has access to the GPU device.
4. If the driver loaded but the GPU isn't visible, the card may have failed. Try a different PCIe slot, or test the card in another machine.

When to escalate

Stoa is delivered as a partnership. For anything beyond the runbook above, contact your delivery engineer. Subtle bugs, recurring degradation that nothing here explains, and anything that touches the database directly are not problems you should be debugging alone.

Next

• What to monitor so you catch problems before they escalate.
• Disaster recovery for the worst case.