Fix LangChain OutputParserException: List for a String Field

TL;DR: LangChain's PydanticOutputParser raises OutputParserException wrapping pydantic_core.ValidationError: string_type because _parse_obj() calls model_validate() with no list-to-string coercion; fix it with a Pydantic mode="before" field validator, or move to with_structured_output(method="function_calling").

The error fires when a model returns a JSON array for a field the schema types as str, and it tends to appear only after switching to a larger model that is weaker at structured output - the smaller model happened to always emit a string for the same prompt and schema. Most guides treat it as a prompt-formatting problem, but the reporter in issue #36603 still hit a 30% failure rate after prompt tuning, because _parse_obj() passes the model's output straight to model_validate() without adapting the type. It sits in the same family as other LangChain output parsing errors, but it is the only one where the parser has a coercion path it never takes.

Why does PydanticOutputParser throw OutputParserException for a list?

The failure is in PydanticOutputParser._parse_obj() at langchain_core/output_parsers/pydantic.py. The method takes the JSON the model returned, hands it straight to self.pydantic_object.model_validate(obj), and lets Pydantic v2 strict validation run. When the model returns "required_changes": ["...", "...", "..."] for a field declared str, Pydantic raises Input should be a valid string [type=string_type, input_type=list], and the parser wraps it as langchain_core.exceptions.OutputParserException: Failed to parse EmailModel from completion {...}. There is no fallback. The parser does not retry or coerce the value, as the issue's root-cause analysis of _parse_obj() calling model_validate() with no type adaptation confirms.

The same prompt and schema ran cleanly against a smaller model (gpt-oss:latest via Ollama) because that model happened to always format the field as a single string. Switching to gpt-oss:120b-cloud surfaced the bug - the larger model expanded the string into a list whenever the field description implied several items. The reporter filed it against langchain_core 1.2.26 and pydantic 2.12.5; the behavior is unchanged in langchain-core 1.5.x as of August 2026, because the proposed upstream fix was closed without merging.

How do you fix the string_type validation error?

Add a mode="before" field validator that joins a list into a string before Pydantic validates the field. Because _parse_obj() calls model_validate(), the validator runs and coerces the value before the string_type check fires.

from pydantic import BaseModel, field_validator

class EmailModel(BaseModel):
    required_changes: str
    violation_types: str

    @field_validator("required_changes", "violation_types", mode="before")
    @classmethod
    def coerce_list_to_str(cls, v):
        if isinstance(v, list):
            return " ".join(str(item) for item in v)
        return v

If the field genuinely carries multiple values, join with a separator that fits the downstream consumer - semicolons, newlines, or a numbered list. Reach for Union[str, list[str]] only if you want the field to stay a list in some code paths, because then every reader of that field has to handle both shapes.

To verify, re-run the same prompt that triggered the error. A successful parse returns an EmailModel instance with required_changes as a single string, and the OutputParserException is gone. Run it 10 or more times, because the original failure was intermittent - the model does not emit the list on every call.

Does with_structured_output() avoid the error?

Yes, and it is the more durable fix. with_structured_output(method="function_calling") pushes the Pydantic schema into the model's tool-calling API, so the model is constrained to emit values that match the declared types rather than free-text JSON that gets parsed after the fact. The list-for-string mismatch becomes far rarer because the API layer enforces the type contract, not post-hoc validation. The trade-off lines up with the LangChain vs LangGraph decision - once an agent loops or holds state across turns, LangGraph's tool-calling runtime sidesteps this whole error class.

One caveat: with_structured_output(method="json_schema") can still hit the mismatch, because the schema get_format_instructions() emits and the schema the model API enforces internally can drift, as the issue's root-cause comment notes. Prefer method="function_calling" when the provider supports it.

What if the error still appears after the fix?

Three remaining causes, in order of likelihood. First, the model is too weak at structured output for the task - the issue's conclusion was that gpt-oss:120b is a relatively weaker and simpler model for extracting structured output, and moving to a more capable model (Claude Sonnet, GPT-4-class) dropped the failure rate. Second, the prompt still invites a list - fields whose description says "list all" or "each" get expanded regardless of schema, so rewrite the description to say "a single string containing." Third, a non-string field has the inverse problem (a string returned for a list field), which the same validator pattern handles in reverse.

An upstream fix exists: PR #38996 adds list-to-str and str-to-list coercion inside PydanticOutputParser, but it was closed without merging, so the parser still has no built-in coercion in langchain-core 1.5.x and the user-side validator remains required. For broader context on recoverable failures in the framework, see error handling in custom LangChain tools; this specific error is also catalogued in the Automation Error Index.

FAQ

Why does PydanticOutputParser raise OutputParserException instead of coercing the list?

_parse_obj() passes the model's JSON straight to model_validate(), which is Pydantic v2 strict validation. A list handed to a str field fails the string_type check, and the parser wraps the ValidationError as OutputParserException rather than adapting the value.

Why did this start only after I switched to a larger model?

Larger-but-weaker-at-structured-output models expand a str field into a list when the description implies multiple items, while the smaller model happened to always return a single string for the same prompt. The bug was always latent in the parser; the model switch exposed it.

Should I fix the prompt or the Pydantic schema?

Fix the schema with a mode="before" validator. The issue reporter still hit a 30% failure rate after prompt tuning alone, because the cause is the parser's lack of coercion, not the prompt. Prompt changes help at the margin but do not make the failure impossible.

Does with_structured_output() avoid this error?

With method="function_calling", mostly yes - the model's tool-calling API enforces the schema, so list-for-string mismatches become rare. With method="json_schema", the mismatch can still occur because the format-instructions schema and the API-enforced schema can drift.

How do I make a field accept both list and string in Pydantic?

Declare it Union[str, list[str]] and add a mode="before" validator that normalizes both shapes to one canonical type, or keep the field str and join any list in the validator. The validator approach keeps the downstream type simple.

Is there an upstream fix in langchain-core?

Not merged. PR #38996 proposed list-to-str and str-to-list coercion inside PydanticOutputParser in July 2026 but was closed without merging, so langchain-core 1.5.x still requires the user-side validator.