Common workflow failures

Most broken workflows fail for one of eight reasons. Each entry states what you see, why it happens, where to look, and what to change.

1. Unresolved expression

Symptom — the step fails with unresolved expression, naming a field. Cause — the template reads a value that does not exist on this path: a node that was skipped by a branch, a renamed node id, or a payload field the caller did not send. Look at — the step log of the previous step; compare its actual output shape with the expression. Fix — reference the node that definitely ran ($node["id"]), guard the read with an IF Condition, or supply a default in a Data Transform.

2. Agent answers but never acts

Symptom — the run completes, the answer sounds plausible, nothing changed in ServiceDesk Plus. Activity count is zero. Cause — the capability node is on the main flow instead of the agent’s tools inlet, or the bound agent has no tool granted. Look at — the canvas edges into the agent, then the agent’s Knowledge tab. Fix — connect the provider node to the tools inlet with a dashed edge; grant the tool; unlock write tools with a procedure.

3. Nothing happens after the branch

Symptom — the run ends early, status looks successful, the steps after the condition never appear. Cause — the branch output that was activated has no edge, or the edge was connected to the wrong handle (true versus false). Look at — the run timeline: which handle was active. Fix — connect the missing edge. Verify both branches independently with Run to this node.

4. Run stuck at “Waiting for input”

Symptom — the run never completes; Enterprise Audit shows Waiting for input. Cause — a write tool requires approval and the request is still undecided. Look at — Approvals view, which names the action, the requesting run and the wait time. Fix — decide it, or change the agent’s approval policy if unattended automation is intended — and accept the risk that implies.

5. Rejected with 401 or 403

Symptom — the webhook call never creates a run. Cause — 401: the key is missing, revoked, or bound to another target. 403: the portal is outside the actor’s scope. Look at — the caller’s headers, then Webhook keys. Fix — use the key minted for this target; resolve the portal from the payload rather than a literal.

6. Loop that never converges

Symptom — the run hits the iteration or item limit; the model repeats the same tool call. Cause — the tool returns something the model cannot use (an error string, an empty array) and the model retries. Look at — the tool call results in the step log. Fix — fix the tool or the query, not the prompt; and lower the limit until the cause is clear.

7. Tool timeout

Symptom — one step fails with a timeout while the rest is healthy. Cause — the remote system is slow, or the timeout is set below the realistic response time of that operation. Look at — the step duration versus the configured timeout. Fix — raise the timeout for that call, or split the operation; a loop that retries the same call does not resolve it.

8. Draft graph that never fires

Symptom — the schedule or webhook produces nothing; manual runs work. Cause — the workflow is still a draft, or the schedule is not registered. Look at — the header status (Draft / Active). Fix — activate the workflow after preflight validation passes.

Fast triage

Question	Where to look
Did the run start at all?	Enterprise Audit → Requests (inbound)
Which step failed?	Run timeline, first failed status
Did anything change outside MAIA Plus?	Enterprise Audit → External Actions
Who allowed it?	Enterprise Audit → Approvals
Is the provider healthy?	Diagnostics

Testing and debugging · Expressions and context · Enterprise Audit · Troubleshooting: workflow execution