GroqParseError
groq.client.errors.GroqParseError
Stack trace
groq.client.errors.GroqParseError: Failed to parse JSON mode response: unexpected token at position 0
File "app.py", line 42, in query_groq
response = client.query(json_mode=True)
File "groq/client.py", line 128, in query
raise GroqParseError("Failed to parse JSON mode response") Why it happens
Groq's JSON mode expects the LLM to return strictly valid JSON without any extra characters, markdown fences, or preamble text. If the LLM returns output with markdown formatting, extra whitespace, or partial JSON, the parser raises this error. This often happens when the prompt does not explicitly instruct the model to return raw JSON or when using models that do not reliably follow output format instructions.
Detection
Monitor Groq client responses for GroqParseError exceptions and log the raw LLM output to detect format mismatches before the error propagates.
Causes & fixes
LLM response includes markdown fences or extra formatting around JSON
Modify the prompt to explicitly instruct the model to return raw JSON only, without markdown fences or extra text.
Prompt does not clearly specify the JSON output format
Add clear instructions in the prompt to return valid JSON only, e.g., 'Respond with only valid JSON, no explanations or markdown.'
Using a base model that ignores output format instructions
Switch to an instruction-tuned model known to follow output format instructions reliably.
Code: broken vs fixed
from groq import GroqClient
client = GroqClient(api_key=os.environ['GROQ_API_KEY'])
response = client.query(json_mode=True) # This line raises GroqParseError
print(response)import os
from groq import GroqClient
client = GroqClient(api_key=os.environ['GROQ_API_KEY'])
prompt = "Return ONLY raw JSON, no markdown fences or extra text."
response = client.query(prompt=prompt, json_mode=True) # Added prompt to enforce raw JSON
print(response)Workaround
Catch GroqParseError, extract JSON substring from the raw response using regex, then parse it manually with json.loads() as a fallback.
Prevention
Use structured output features or response_format parameters at the API level to guarantee schema-valid JSON responses, avoiding parser fragility.