Failure Modes and Debugging

A wrong answer has a cause at one specific stage. In pipeline order:

• 1. Missing content: the answer is not in any document.
• 2. Missed retrieval: it is in the index but was not in the retrieved candidates.
• 3. Lost in ranking: it was retrieved but ranked too low to reach the prompt.
• 4. Not used: it was in the prompt and the model ignored it.
• 5. Wrong format or incomplete: the model used it but left part out or shaped the answer badly.
• 6. Hallucinated detail: the model added something the context did not say.
• 7. Stale or conflicting source: the context itself was outdated or contradicted another chunk.

Naming the stage is most of the work, because each has a different owner and a different fix. An interviewer who asks 'your RAG system gives wrong answers, what do you do?' wants to hear this list and a method for telling the cases apart, not a guess at a fix.

One question splits every failure in two: was the chunk containing the right answer in the prompt?

• Look at the logged context for the failed question.
• If the right chunk is absent, it is a retrieval-side problem.
• If it is present, it is a generation-side problem.

This single check halves the search and takes a minute.

• From there, follow the pipeline backwards for retrieval failures: is the fact in the documents at all? Is it in a chunk in one piece?
• Was that chunk in the first-stage candidates? Did the reranker drop it? The first 'no' is the broken stage.

The question is reasonable, but the answer is not in the collection: nobody wrote it down, the document was never ingested, or the parser failed on that file. The retriever returns its nearest chunks anyway, and the model, handed plausible-looking context, often produces a plausible-looking answer.

This is common in real traffic, and it is the case that most needs abstention. It is also valuable signal: a log of questions that had no good match is a list of the documents your organisation needs to write.

The answer exists in a chunk, but that chunk was not among the retrieved candidates. Usual causes:

• the question and the chunk use different words and the search is keyword-only;
• the question contains an exact code and the search is dense-only;
• the fact was split across two chunks;
• the chunk is ambiguous on its own ("the fee is refunded", with no mention of which fee);
• the query was a follow-up fragment;
• a filter excluded it.

Each cause maps to a technique from an earlier module, which is why those modules exist:

• Different words: hybrid search, multi-query.
• Exact codes: keyword search.
• Split facts: overlap, structure-aware chunking.
• Ambiguous chunks: contextual headers.
• Fragments: query rewriting.
• Filters: check the metadata.

The right chunk was in the prompt and the model still answered wrongly or said it did not know. Usual causes:

• the chunk sat in the middle of a long context;
• it was surrounded by distracting chunks that looked relevant and pointed elsewhere;
• the chunk was hard to read (a flattened table, broken formatting);
• the instructions were so cautious that the model abstained despite having the answer.

It shows that retrieval being right is necessary and not sufficient. The fixes are about making the right chunk easy to use: fewer chunks, best first, clean formatting, clear labels, and instructions that balance caution against answering.

The context was right and the model still stated something it does not support. Typical forms:

• adding a plausible detail (a time limit the policy never mentions);
• merging two chunks into a rule neither states;
• over-generalising (the policy covers late orders; the answer says 'all orders');
• getting numbers slightly wrong.

This is the residual risk that no retrieval improvement removes, so it needs its own defences: a firm grounding instruction, a citation per claim, a low temperature, an automatic groundedness check on the output, and for high-stakes answers a second model pass that verifies each claim before the user sees it.

The system retrieves and faithfully reports a passage that is out of date, or retrieves two passages that disagree: last year's policy and this year's, a draft and the final version, a regional rule and the global one. The model then picks one, or blends them.

It is a data problem appearing as a model problem, and common in any organisation whose documents were never tidied. Fixes sit in ingestion: remove or archive superseded versions, store an updated_at date and a status on every chunk, filter or down-rank old content, show the date to the model in the context, and instruct it to prefer the most recent source and to say so when sources conflict.

A trace is a record of everything that happened for one question: the original message, the rewritten query, the filters applied, the candidate chunks with their scores, the reranked order, the final prompt, the model's answer, the time and cost of each step, and any user feedback. Each trace has an ID that ties the pieces together.

Every debugging step in this module depends on it.

• Without traces, a reported wrong answer cannot be reproduced, because the documents, the index and the prompt may all have changed since.
• With them, diagnosis takes minutes, and failed traces can be added straight to the golden set.