Diagnosing Unexpected Outputs
Classifying failure modes: wrong answer, wrong format, off-topic, hallucination.
Diagnosing Unexpected Outputs is a free AI Prompt Engineering lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the AI Prompt Engineering learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
When Prompts Fail
Even carefully crafted prompts produce wrong results. Diagnosing failures requires a taxonomy — a classification of what type of failure occurred. Without classification, debugging is guesswork. The four main failure categories are: wrong answer, wrong format, off-topic response, and hallucination.
Failure Type 1: Wrong Answer
A wrong answer is a factual error — the model gave a response in the correct format and on the correct topic, but the content is incorrect.
Examples: dates, statistics, names, code that has a logic bug. This is the hardest failure to detect automatically because the output looks correct on the surface.
- Cause: training data cutoff, rare fact, or multi-step reasoning error
- Detection: compare against ground truth, human review, or a verification LLM call
# Example: wrong answer failure
prompt = 'What year was Python first released?'
response = 'Python was first released in 1994.' # Wrong — it was 1991
# Ground truth check
GROUND_TRUTH = '1991'
correct = GROUND_TRUTH in response
print(f'Correct: {correct}') # FalseFailure Type 2: Wrong Format
A wrong format failure occurs when the model answered the right question with the right information, but ignored the formatting instruction.
Examples: returned plain text when JSON was requested, added markdown when plain text was required, returned a list when a single value was asked for.
- Cause: formatting instruction buried in a long prompt, conflicting instructions, model ignoring low-priority instructions
- Detection: JSON parse error, regex mismatch, schema validation failure
import json
response_text = 'Sure! Here is the result: {"name": "Alice", "age": 30}'
try:
data = json.loads(response_text)
print('Format OK:', data)
except json.JSONDecodeError as e:
print(f'FORMAT FAILURE: {e}')
# 'Sure! Here is the result:' prefix broke JSON parsingFailure Type 3: Off-Topic Response
An off-topic failure means the model answered a different question than the one asked. The response may be factually correct and well-formatted, but it does not address the user's actual intent.
Examples: asked for a Python function, received a JavaScript function; asked for a one-line answer, received a full essay; asked to fix a bug, received an explanation of the bug instead of the fix.
- Cause: ambiguous instruction, conflicting context, task drift in long conversations
# Off-topic example
prompt = 'Write a Python function that reverses a list.'
response = '''
In JavaScript, you can reverse an array like this:
const reversed = arr.reverse();
'''
# Detection: check that output contains the correct language keyword
def check_language(response, expected_lang='def '):
if expected_lang not in response:
print(f'OFF-TOPIC FAILURE: expected {expected_lang} in response')
return False
return True
check_language(response) # False — no Python defFailure Type 4: Hallucination
Hallucination is the most dangerous failure: the model invents facts that do not exist. These look plausible and confident, making them hard to spot.
Examples: fabricated citations (paper title sounds real but doesn't exist), invented API endpoints, fake statistics, non-existent people.
- Cause: the model fills knowledge gaps with pattern-matched plausible text
- Detection: fact-check against authoritative sources, cross-reference citations, test API calls
# Hallucination detection via external verification
import requests
def verify_doi(doi):
url = f'https://doi.org/{doi}'
resp = requests.head(url, allow_redirects=True, timeout=5)
return resp.status_code == 200
# Model claimed this paper exists:
fabricated_doi = '10.1234/fake.paper.2023.99999'
if not verify_doi(fabricated_doi):
print('HALLUCINATION DETECTED: DOI does not exist')The Failure Taxonomy in Practice
When a failure is observed, classify it first before attempting a fix. The failure type determines the fix strategy:
- Wrong answer: add context, use retrieval, or switch to a more capable model
- Wrong format: strengthen the format instruction, add output examples, use structured outputs / function calling
- Off-topic: rewrite instruction to be more specific, simplify the prompt
- Hallucination: add grounding context, instruct to say 'I don't know', enable citations
Structured Failure Logging
Log every failure with its classification. Over time, patterns emerge: a specific prompt section causes most wrong-format errors, or a specific topic triggers frequent hallucinations. Structured logs enable data-driven debugging.
import json
from datetime import datetime
def log_failure(prompt, response, failure_type, details=''):
entry = {
'timestamp': datetime.utcnow().isoformat(),
'failure_type': failure_type, # wrong_answer | wrong_format | off_topic | hallucination
'prompt_hash': hash(prompt),
'response_snippet': response[:200],
'details': details
}
with open('prompt_failures.jsonl', 'a') as f:
f.write(json.dumps(entry) + '\n')
log_failure(
prompt=my_prompt,
response=bad_response,
failure_type='wrong_format',
details='JSON prefix text broke parsing'
)Automated Failure Classification
For large-scale testing, use a classifier LLM call to automatically label each response with a failure type. This enables batch evaluation across hundreds of test cases.
def classify_failure(prompt, expected, actual):
classification_prompt = (
f'You are a QA evaluator for LLM outputs.\n'
f'Prompt: {prompt}\n'
f'Expected behavior: {expected}\n'
f'Actual output: {actual}\n\n'
'Classify the failure as one of: CORRECT, WRONG_ANSWER, WRONG_FORMAT, OFF_TOPIC, HALLUCINATION.\n'
'Reply with only the label.'
)
resp = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': classification_prompt}]
)
return resp.choices[0].message.content.strip()Severity Matrix
Not all failures have equal impact. A severity matrix helps prioritize fixes:
- Hallucination in medical/legal context: critical — fix immediately
- Wrong format in internal tool: high — breaks downstream parsing
- Wrong answer on rare edge case: medium — monitor frequency
- Off-topic on ambiguous input: low — acceptable if infrequent
Track failure rates per type per week. A spike in any category signals a regression that needs attention.
Building a Failure Dashboard
A simple failure dashboard reads the failure log and reports counts by type and by prompt section:
import json
from collections import Counter
def failure_report(log_path='prompt_failures.jsonl'):
entries = []
with open(log_path) as f:
for line in f:
entries.append(json.loads(line))
counts = Counter(e['failure_type'] for e in entries)
total = len(entries)
print(f'Total failures: {total}')
for ftype, count in counts.most_common():
pct = 100 * count / total
print(f' {ftype}: {count} ({pct:.1f}%)')
failure_report()Preventing Failures Proactively
Proactive strategies to reduce each failure type before they occur:
- Wrong answer: provide reference text in the prompt (RAG); ask the model to cite its source
- Wrong format: use JSON mode or function calling; provide a format example in the prompt
- Off-topic: make the task the first sentence; avoid long preambles that dilute intent
- Hallucination: instruct 'Only use information provided below'; add 'If unsure, say I don't know'
Knowledge Check
Which failure type occurs when the model invents facts that do not exist, such as fabricating a citation or a non-existent API endpoint?
Recap: Diagnosing Unexpected Outputs
The four LLM failure types and their key characteristics:
- Wrong answer: correct format, correct topic, wrong content — fact-check against ground truth
- Wrong format: correct content, ignored format instruction — schema validation catches this
- Off-topic: correct format, answered a different question — check language/task match
- Hallucination: invented facts — verify against external sources
Log and classify every failure. Track rates by type over time. Next lesson: root cause analysis to find which part of the prompt caused the failure.
Frequently asked questions
Is the “Diagnosing Unexpected Outputs” lesson free?
Yes — the full text of “Diagnosing Unexpected Outputs” is free to read here on the web, and the AI Prompt Engineering course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the AI Prompt Engineering course, upgrade to CoddyKit PRO.
What will I learn in “Diagnosing Unexpected Outputs”?
Classifying failure modes: wrong answer, wrong format, off-topic, hallucination. You practise AI Prompt Engineering with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start AI Prompt Engineering?
No prior experience is required. AI Prompt Engineering on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Diagnosing Unexpected Outputs” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this AI Prompt Engineering lesson?
Yes. Every AI Prompt Engineering lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Diagnosing Unexpected Outputs
- Root Cause Analysis for Prompts
- Systematic Debugging Approach
- Logging and Documentation Strategies