Debugging LangChain JSON Output

LangChain and Structured Output

LangChain provides several mechanisms for getting structured JSON output from language models: JsonOutputParser, PydanticOutputParser,StructuredOutputParser, and the newer with_structured_output() method. Despite these abstractions, JSON parse errors are one of the most frequently encountered runtime errors in LangChain applications.

The failures come from two directions: the model produces non-conforming output that the parser cannot handle, or the model produces technically valid JSON that does not match the expected Pydantic schema. AI JSONMedic helps with the first category — repairing the raw string so it becomes parseable — giving you clean data to validate against your schema separately.

OutputParserException: What It Actually Means

When LangChain raises OutputParserException, the error message is often cryptic. It typically looks like:

langchain_core.exceptions.OutputParserException:
  Failed to parse. Got:
  Got invalid return object. Expected key `action` to be present,
  got: ```json
{"thought": "I need to search", "action": "search"...

The underlying issue here is that the model wrapped its JSON in a markdown code fence. LangChain's parser received the raw string including the backticks. Copy the raw output string and paste it into AI JSONMedic — the markdown stripping stage handles this pattern immediately.

Tool Call JSON Repair

LangGraph agents using tool calls (function calling) produce JSON arguments that must conform exactly to the tool's input schema. A common failure is when the model generates an argument value as a string-encoded JSON object when the schema expects a plain object:

// Model returned this (wrong — nested JSON encoded as string):
{
  "query": "{\"filter\": {\"status\": \"active\"}}"
}

// Schema expects this (correct — nested object):
{
  "query": {
    "filter": {
      "status": "active"
    }
  }
}

While AI JSONMedic does not perform semantic schema coercion, it will validate the structure and help you identify exactly where the model deviated from the expected format — which is the first step to fixing the prompt or output parser.

Debugging LangChain ReAct Agents

ReAct-style agents (Reason + Act) produce intermediate JSON for thought/action cycles. These are especially prone to errors because the model generates JSON embedded within a longer text response, and the chain must extract and parse it correctly:

// Typical ReAct agent output (this is what arrives at the parser):
Thought: I need to look up the current weather.
Action: search_weather
Action Input: {"location": "London", "units": "metric",}

// The trailing comma on the last field breaks JSON.parse()

AI JSONMedic's trailing comma removal handles this instantly. Paste just the Action Input portion and get clean JSON back.

PydanticOutputParser and Validation Errors

PydanticOutputParser raises two distinct types of errors: JSON parse errors (the string is not valid JSON) and Pydantic validation errors (the JSON is valid but does not match the model). AI JSONMedic solves the first type.

Here is a diagnostic workflow for OutputParserException:

1. Add verbose=True to your chain or use langchain.debug = True to log the raw LLM output
2. Copy the raw string from the log — everything the model returned before the parser ran
3. Paste it into AI JSONMedic and run the fixer
4. If the fixer produces valid JSON, the problem is a syntax issue in the model's output — update your prompt to be more explicit
5. If the fixer produces valid JSON but your Pydantic model still fails, the problem is a schema mismatch — review the field types and optional vs required fields

LangGraph Multi-Agent Workflows

LangGraph workflows pass state as JSON between nodes. When an agent node modifies state and returns a malformed object, the entire graph execution fails. Debugging multi-agent state transitions is particularly challenging because the failure may be in a node that is several steps removed from the actual data source.

Use the AI JSONMedic Diff tool to compare the state object before and after a problematic node — this quickly reveals what the node changed and whether those changes are structurally valid.

Production Resilience Pattern

For production LangChain applications, consider wrapping your output parser with a retry mechanism that uses repair logic on parse failure:

import json
from langchain_core.output_parsers import JsonOutputParser
from langchain_core.exceptions import OutputParserException

class ResilientJsonParser(JsonOutputParser):
    def parse(self, text: str) -> dict:
        try:
            return super().parse(text)
        except OutputParserException:
            # Strip markdown fences — the most common cause
            cleaned = text.strip()
            if cleaned.startswith("```"):
                cleaned = cleaned.split("\n", 1)[-1]
                cleaned = cleaned.rsplit("```", 1)[0].strip()
            # Strip Python booleans
            import re
            cleaned = re.sub(r'\bTrue\b', 'true', cleaned)
            cleaned = re.sub(r'\bFalse\b', 'false', cleaned)
            cleaned = re.sub(r'\bNone\b', 'null', cleaned)
            # Remove trailing commas
            cleaned = re.sub(r',\s*([}\]])', r'\1', cleaned)
            try:
                return json.loads(cleaned)
            except json.JSONDecodeError:
                raise OutputParserException(
                    f"Could not parse even after cleanup: {text[:200]}"
                )

This covers the most common cases. Paste the raw string into AI JSONMedic during development to understand the exact failure mode before writing cleanup code for it.