Troubleshooting

Most MAIA Plus problems are answered by four questions in a fixed order. Working through them beats guessing, because each one either finds the fault or eliminates a whole layer.

The four questions

#	Question	Where to look	If the answer is no
1	Did the request arrive?	Enterprise Audit → Requests	The problem is outside MAIA Plus: the caller, the key, the network
2	Did the run start and finish?	Audit → Runs	A paused run is an approval; a failed run names the step
3	Did anything leave the system?	Audit → External Actions	The agent answered but never called a tool
4	Is the configuration healthy now?	Diagnostics	A pending restart or a failing validation explains “I changed it and nothing happened”

Symptom → article

Symptom	Start here
A webhook “does nothing”	Connections
Answers are slow, wrong or empty	Providers
401 / 403 / scope errors	Permissions
A document is uploaded but never found	Knowledge indexing
A workflow ends early, fails, or waits forever	Workflow execution · Common workflow failures
Everything looks configured but nothing works	Diagnostics
Short answers to common questions	FAQ

Triage rules

• Read the first failure, not the last error. Cascading failures are noise.
• Check the revision. A run records the configuration revision it used; compare before blaming the current one.
• Do not repeat an unclear action. A second identical attempt hides the first result.
• Collect evidence before touching anything: run id, timestamp, target, and the audit view.
• Never paste secrets, tokens or raw stack traces into a ticket.

What the evidence should contain

When you escalate, send: the run id, the target endpoint, the timestamp with timezone, which audit view you checked, and what the step log said. That is enough to reproduce; everything else is usually sensitive.

Related topics

Diagnostics · Enterprise Audit · Common workflow failures · FAQ