InstructorMaxRetriesExceededParseError
instructor.errors.InstructorMaxRetriesExceededParseError
Stack trace
instructor.errors.InstructorMaxRetriesExceededParseError: Maximum retries exceeded while attempting to parse LLM output
File "/usr/local/lib/python3.9/site-packages/instructor/parser.py", line 142, in parse_with_retries
raise InstructorMaxRetriesExceededParseError("Max retries exceeded parse error")
File "/usr/local/lib/python3.9/site-packages/instructor/parser.py", line 120, in parse
parsed = self._parse_raw_output(raw_output)
File "/usr/local/lib/python3.9/site-packages/instructor/parser.py", line 85, in _parse_raw_output
raise ParseError("Failed to parse output") Why it happens
The instructor library expects the LLM output to conform to a strict format for parsing. If the output deviates due to markdown fences, unexpected text, or format inconsistencies, the parser retries. When all retry attempts fail, this error is raised indicating persistent parse failure.
Detection
Monitor parse attempts and catch InstructorMaxRetriesExceededParseError exceptions; log raw LLM outputs on failure to identify format mismatches before the retries are exhausted.
Causes & fixes
LLM output includes markdown fences or extra formatting around the expected JSON or structured data
Modify the prompt to instruct the LLM to return raw JSON without markdown fences or use a parser that automatically strips markdown fences.
The prompt or schema expects fields that do not match the actual LLM output keys or structure
Ensure the prompt instructions and the parsing schema are aligned exactly with the expected field names and output format.
Using a base LLM model that does not reliably follow output format instructions, causing inconsistent responses
Switch to an instruction-tuned model known to follow output format instructions, such as gpt-4o-mini or claude-3-5-haiku-20241022.
Code: broken vs fixed
from instructor import Instructor
instructor = Instructor(max_retries=3)
response = instructor.parse(raw_llm_output) # This line raises InstructorMaxRetriesExceededParseErrorimport os
from instructor import Instructor
instructor = Instructor(max_retries=3)
# Added prompt instruction to avoid markdown fences and ensure raw JSON output
prompt = "Return ONLY raw JSON without markdown fences."
raw_llm_output = get_llm_output_with_prompt(prompt) # hypothetical function
response = instructor.parse(raw_llm_output) # Fixed: output matches expected format
print(response)Workaround
Catch InstructorMaxRetriesExceededParseError, extract JSON manually from the raw LLM output using regex to remove markdown fences, then parse with json.loads() as a fallback.
Prevention
Use structured output features of the LLM API or instruction-tuned models that guarantee schema-valid responses, eliminating parser fragility and retry exhaustion.