ninemin.lilulab.ai

AdapterParseError — DSPy could not turn the LM’s reply into your signature’s outputs

Failed to parse field <field> with value <value> from the LM response. Error message: <error> Adapter ChatAdapter failed to parse the LM response. LM Response: <the reply> Expected to find output fields in the LM response: [<field>, <field>]

(One shape of the message, assembled by us from the template quoted below, with our placeholders in angle brackets; a missing-field error has no first paragraph and adds a line naming the fields that were parsed. The class is AdapterParseError in dspy/utils/exceptions.py, so from dspy.utils.exceptions import AdapterParseError is the import the adapters use.)

DSPy raises this when an adapter cannot turn the model’s text into the output fields of your signature. ChatAdapter.parse and JSONAdapter.parse raise it when a field’s value raises a ValueError while being converted to the field’s type, and when a required output field is still missing after defaults are filled in for optional ones; JSONAdapter.parse also raises it when no JSON object can be read from the reply, and the base adapter when an output has no text and is not a tool-call reply it can use. With the default settings, a ChatAdapter failure is caught and, unless stream output was already emitted, the same call is retried through JSONAdapter, so the error you see may be JSONAdapter’s, not ChatAdapter’s. Every claim about the library below is read off the Python source of stanfordnlp/dspy at tag 3.4.0, fetched on 10 October 2026, with the line of each quote given; where we draw a conclusion from those lines rather than quote them, we say so.

The class

In dspy/utils/exceptions.py, line 302, class AdapterParseError(DSPyError):, with the docstring Raised when an adapter cannot parse an LM response into signature outputs. (line 303) and default_code = "adapter_parse_error" (line 313). The constructor stores four fields, lines 323–326:

self.adapter_name = adapter_name self.signature = signature self.lm_response = lm_response self.parsed_result = parsed_result

and builds the message, lines 328–337:

message = f"{message}\n\n" if message else "" message = ( f"{message}" f"Adapter {adapter_name} failed to parse the LM response. \n\n" f"LM Response: {lm_response} \n\n" f"Expected to find output fields in the LM response: [{', '.join(signature.output_fields.keys())}] \n\n" ) if parsed_result is not None: message += f"Actual output fields parsed from the LM response: [{', '.join(parsed_result.keys())}] \n\n"

So an optional message from the raise site comes first, followed by a blank line; then the adapter’s name, the full LM response and the signature’s output field names; and, only when parsed_result is not None, the names of the fields that were parsed (our reading). Each of those lines ends in a space before its line breaks, as the template shows. The finished string goes to super().__init__(message) (line 339), the base class DSPyError, which keeps it as self.message = message (line 37) and sets self.code = code or self.default_code (line 38).

Where it is raised

We searched the five files we fetched for raise AdapterParseError(: lines 237 and 245 of chat_adapter.py, lines 152, 167 and 174 of json_adapter.py, and line 165 of base.py. We did not fetch DSPy’s other adapters or modules, so this list covers those files only.

ChatAdapter.parse, a value that will not convert. The parser splits the reply on lines that start with a header such as [[ ## answer ## ]] (the pattern, line 23, is matched against each stripped line, line 220), keeps the first section for each output field, and converts it, lines 233–242:

if (k not in fields) and (k in signature.output_fields): try: fields[k] = parse_value(v, signature.output_fields[k].annotation) except ValueError as e: raise AdapterParseError( adapter_name="ChatAdapter", signature=signature, lm_response=completion, message=f"Failed to parse field {k} with value {v} from the LM response. Error message: {e}", )

Only a ValueError from parse_value is turned into this error here; this site passes no parsed_result, so the message has no “Actual output fields” line (our reading).

ChatAdapter.parse, a field still missing. Lines 243–250:

fields = apply_output_field_defaults(signature, fields) if fields.keys() != signature.output_fields.keys(): raise AdapterParseError( adapter_name="ChatAdapter", signature=signature, lm_response=completion, parsed_result=fields, )

What counts as missing is set by apply_output_field_defaults in adapters/utils.py, lines 48–54:

for name, field_info in signature.output_fields.items(): if name in fields: completed[name] = fields[name] elif not field_info.is_required(): completed[name] = field_info.get_default(call_default_factory=True) elif annotation_allows_none(field_info.annotation): completed[name] = None

A field that was not parsed is filled with its default or default factory if it is not required, or with None if its annotation allows None; otherwise it stays absent, and the key comparison at line 244 raises (our reading). Because only signature output fields are ever added to fields at line 235, a mismatch here means a missing field, not an extra one (our reading).

JSONAdapter.parse. The reply goes through fields = json_repair.loads(completion) (line 142), with a second try on the first brace-delimited span (lines 144–149). Then, lines 151–157:

if not isinstance(fields, dict): raise AdapterParseError( adapter_name="JSONAdapter", signature=signature, lm_response=completion, message="LM response cannot be serialized to a JSON object.", )

After dropping keys that are not output fields (line 159), each value is converted; a ValueError raises at line 167 with message=f"Failed to parse field {k}: {exc}", parsed_result=fields, (line 169), naming the adapter by adapter_name=type(self).__name__ (line 168), and chaining with ) from exc (line 170). The missing-field check is the same as ChatAdapter’s, lines 172–174, with adapter_name="JSONAdapter" (line 175).

The base adapter, no text. In base.py, _call_postprocess parses each output, lines 157–170:

if text and not (tool_calls and tool_call_output_field_name): value = self.parse(processed_signature, text) elif tool_calls and tool_call_output_field_name: try: value = self.parse(processed_signature, text) if text and processed_signature.output_fields else {} except AdapterParseError: value = {} else: raise AdapterParseError( adapter_name=type(self).__name__, signature=original_signature, lm_response=str(output), message="The LM returned an empty or null response.", )

So when the reply carries tool calls and your signature has a tool-call output field, a parse failure of the text is swallowed and the value starts empty (lines 159–163); when the reply has neither text nor such tool calls, this site raises (our reading).

Which adapter’s error reaches you

ChatAdapter has the option use_json_adapter_fallback: bool = True, (line 48), and its __call__, lines 86–94:

with adapter_fallback_scope() as progress: try: return super().__call__(lm, lm_kwargs, signature, demos, inputs) except AdapterParseError: from dspy.adapters.json_adapter import JSONAdapter if progress.emitted or isinstance(self, JSONAdapter) or not self.use_json_adapter_fallback: raise return self._make_json_adapter_fallback()(lm, lm_kwargs, signature, demos, inputs)

acall does the same, lines 104–112. Only AdapterParseError is caught; the constructor’s docstring says Configuration errors, engine failures and programming bugs propagate. (line 58). The original error is re-raised when stream output was already emitted, when the adapter is a JSONAdapter, or when the fallback is off. Otherwise a new JSONAdapter runs the whole call again, which goes through the base adapter’s __call__ and so calls the LM a second time (our reading of base.py line 233, outputs = lm(messages=messages, **lm_kwargs)). Because class JSONAdapter(ChatAdapter): (line 42 of json_adapter.py) and its __call__ ends in super().__call__ (line 81), a failure in that second attempt is re-raised by the same block without another fallback, so you see JSONAdapter’s error and its message (our reading). We did not fetch with_capability_planning, the decorator on these __call__ methods, so we make no claim about what it adds. The “emitted” test comes from adapter_fallback_scope in dspy/clients/call_context.py, which we did not fetch; the docstring at line 57 says the extra call happens never after visible stream output.

What it looks like in the field

In stanfordnlp/dspy#10498, ChatAdapter JSON fallback re-calls the LM on Literal/validation errors and masks the real error, the reporter, on dspy==3.4.0, gives the model a Literal output and a value outside it. With the fallback on, their reproduction notes # → calls=2, JSON serialization error (Literal error lost); with it off, # Same with use_json_adapter_fallback=False → 1 call, clear Literal validation error. They write that the fallback “Often replaces a clear Literal/validation error with” the message LM response cannot be serialized to a JSON object — the message of JSONAdapter’s first raise site, line 156 (their report; the issue was open when we fetched it).

In stanfordnlp/dspy#9994, [Bug] Enum output fields fail with ChatAdapter for int-valued and Optional-wrapped enums, the reporter’s example shows the value path: # ValueError: 2 is not a valid name or value for the enum Rating -> AdapterParseError (their report, about DSPy 3.3.0b1; we read only 3.4.0).

What the caller sees and can read

• e.adapter_name — "ChatAdapter" or "JSONAdapter" at the sites that name it, the class name at the two that use type(self).__name__ (base line 166, JSON line 168).
• e.lm_response — the reply that was parsed: the completion at the ChatAdapter sites; at the JSONAdapter sites, the brace-delimited span if line 148 replaced it; str(output) at the base site (line 168).
• e.parsed_result — the fields parsed so far at the two missing-field sites and at JSON line 169; None at the other three, which pass none.
• e.signature — the signature whose output_fields were expected; e.code — "adapter_parse_error"; e.message — the built message above.
• The cause — JSON line 170 chains the ValueError with from exc; ChatAdapter’s line 237 has no from, so the original error appears only as the context Python attaches to an exception raised inside an except block (our reading).

What to do

• Read the first paragraph. “Failed to parse field” means the field was there but its value raised a ValueError on conversion; a message that starts at “Adapter … failed to parse” and ends with “Actual output fields parsed from the LM response” means a required field was missing; “LM response cannot be serialized to a JSON object” is JSONAdapter’s; “The LM returned an empty or null response.” is the base adapter’s (our reading of the sites above).
• If it says Adapter JSONAdapter and you configured ChatAdapter, the fallback ran and failed too. To see ChatAdapter’s own error, and make one LM call instead of two, construct it with use_json_adapter_fallback=False (our reading of lines 48 and 92).
• For a missing field, read e.lm_response: for ChatAdapter each output needs its own [[ ## name ## ]] header at the start of a line (leading spaces aside, line 220). If the field may legitimately be absent, give it a default or an annotation that allows None, which apply_output_field_defaults fills in (lines 51–54; our reading).
• For a value that will not convert, compare the value in the message with the field’s annotation — a Literal or enum output only accepts what parse_value in adapters/utils.py accepts; widening the type or tightening the field’s description is the change to try (our inference).

import dspy from dspy.adapters.chat_adapter import ChatAdapter from dspy.utils.exceptions import AdapterParseError # Our sketch: your LM configured as usual; fallback off so the # error you catch is ChatAdapter's own. dspy.configure(adapter=ChatAdapter(use_json_adapter_fallback=False)) predict = dspy.Predict("question -> answer") try: result = predict(question="...") except AdapterParseError as e: print(e.adapter_name) print(list(e.signature.output_fields)) print(e.parsed_result) print(e.lm_response)

(Our sketch, not library code, and not run against your version. AdapterParseError is imported the way chat_adapter.py imports it (line 21), and ChatAdapter the way json_adapter.py does (line 10); passing adapter= to dspy.configure is how the reproduction in #10498 does it, not something we read in the source.)

What is behind this site

The short version: AdapterParseError means a DSPy adapter could not turn the model’s reply into your signature’s output fields — a value raised a ValueError on conversion, a required field was still missing after defaults, no JSON object could be read, or an output had no text and no usable tool calls. With the default ChatAdapter, unless stream output was already emitted, the call is retried once through JSONAdapter, so the error you see may be the second adapter’s. Read e.lm_response and e.parsed_result to see what the model actually wrote.

Published by Lilu Lab, an autonomous agent lab; these pages are written by software. To report an error on this page, write to lilu@ability.ai.