When an AI workflow misbehaves, the instinct is to blame the model and rewrite the prompt. Often that is wrong. The model did what it was asked with what it was given, and the problem sits upstream or downstream.
A run trace shows each step's input, output and timing, which is what you need to find where things went wrong. This post describes five failure patterns that show up repeatedly in workflow builds and how each looks in a trace.
A note on honesty. These are illustrative patterns drawn from how workflows typically fail, written as examples. They are not a log of one customer's run, and the data in them is invented to show the shape of the problem.
How to read a trace#
Work from the end backwards. Start with the step that produced the wrong result, and ask: was its input right? If yes, the step itself is faulty. If no, move one step back and repeat. The first step whose input is right and output is wrong is your suspect. Most bugs are found within three hops.
Look at four things for each step: what came in, what went out, how long it took, and whether it reported success. A step that "succeeded" with an empty output is a failure that looks like a pass.
Pattern 1: The empty or unresolved variable#
Symptom. The reply says "Hello ," or the email is missing the order number. The model politely wrote around a gap.
In the trace. The model step's input shows a literal placeholder, or a blank where a value should be. Go back one step: the earlier step returned its data under a different field name, or returned nothing, and the variable reference points at nothing.
Why it happens. A field was renamed, an earlier step failed quietly, or the reference is typed wrong.
Fix. Stop the run when a required value is empty. Add a condition after each step that produces a key value and send empty results to a failure path. Do not let the model paper over missing data.
Pattern 2: The condition that takes the wrong branch#
Symptom. Every invoice goes to the approver, or none of them do. The threshold seems ignored.
In the trace. The condition step shows the value it compared. You see the amount arrive as the text "1,250.00" with a comma, or as a string where the rule expects a number. The comparison returns false or true for the wrong reason.
Why it happens. Data types and formats. Text versus number, a date as a string, a currency symbol, a boolean returned as the word "true".
Fix. Normalise values before comparing. Convert to a number in a step of its own, so the trace shows the clean value. Test every branch with at least one sample that should take it.
Pattern 3: The tool called with the wrong arguments#
Symptom. The agent said it updated the record, but nothing changed. Or it searched for the wrong customer.
In the trace. The tool call step lists the arguments the agent chose. The ID is the customer's name, or the date format is the one the target system rejects, or an optional field was filled with a guess. The tool's response has an error the agent glossed over in its final message.
Why it happens. The tool description is vague, so the model guessed. Or the tool returned an error as ordinary text.
Fix. Write tool descriptions with an example call, say which fields are required, and have tool steps return a clear success or failure. Validate arguments in a step before the call. For anything that changes data, put an approval before it so a person sees the arguments.
Pattern 4: Retrieval that returned the wrong passages#
Symptom. The agent answers confidently but incorrectly, quoting a policy that does not apply, or says it has no information when your documents cover it.
In the trace. The retrieval step shows the chunks it returned. They come from the wrong document, a superseded version, or the right document but the wrong section. Sometimes the query itself is poor: the user's whole message went in as the search text.
Why it happens. Chunks cut in awkward places, outdated content still in the store, or a query that doesn't match the document's vocabulary.
Fix. Preview how your loader and splitter cut documents before embedding. Remove or replace superseded content. Rewrite the query in a step before retrieval so it uses the terms your documents use. Run test questions directly against the store and read the chunks that come back. In Cadrix you can preview chunks, review upsert history and query the store.
Pattern 5: The run that waits forever, or loops forever#
Symptom. A run shows as still going hours later, or a bill is larger than expected.
In the trace. Case one: the run is paused at an approval step and nobody has responded, because the request went to the wrong person or the notification was missed. Case two: a loop step has run many times, and each pass shows nearly identical input and output. The exit condition never becomes true.
Why it happens. No owner for the approval queue, no timeout, or an exit rule that depends on something that never changes.
Fix. Name a role, not just a person, as approver, and decide what happens to silence: remind, escalate, or expire. Set a maximum loop count on every loop, and make each pass change something that the exit condition can see. In Cadrix, runs waiting on a person show as awaiting approval and appear in the Needs you queue, and the Loop step has a maximum loop count.
What to do after you find it#
- Retry or re-run with a fix. Cadrix lets you retry a failed step, or re-run with edits. Either creates a new linked run, so the original stays on record.
- Add the case to your test set. A bug you've seen once will return. Keep the input that triggered it, and run it after every change.
- Ask whether a rule would have caught it. Many of these failures are better prevented by a check than by a smarter prompt.
- Note the cause. A short log of cause and fix teaches the team faster than any guide.
A short debugging routine#
- Open the failing run; find the first step with a right input and a wrong output.
- Read that step's input exactly. Is every value present and well formed?
- Read the output. Is it empty, partial or confident but wrong?
- Check the step before it, and the data type of anything compared.
- For agents, read the tool calls and their results, not just the final message.
- Fix one thing, re-run, and compare traces.
