How to Handle Extraction Errors and Parse Failures in LangExtract

Use the suppress_parse_errors parameter in Resolver.resolve() or extract() to log malformed LLM outputs and continue processing, or catch ResolverParsingError to handle failures explicitly.

LangExtract is a Google open-source library that transforms raw language model outputs—typically JSON or YAML—into structured Extraction objects. When the model returns malformed or unparsable content, the library raises specific exceptions that you can either catch for strict error handling or suppress for resilient batch processing.

Understanding the Error Handling Pipeline

When LangExtract processes LLM output, the core parsing logic resides in langextract/resolver.py. The flow follows these steps:

1. Resolver Initialization – The Resolver class receives optional legacy parameters through resolver_params, including the suppress_parse_errors flag. This parameter is automatically extracted from the configuration dictionary via ALIGNMENT_PARAM_KEYS defined in langextract/resolver.py (lines 45-50).

2. Parsing Attempt – The Resolver.resolve() method delegates to FormatHandler.parse_output() in langextract/core/format_handler.py to decode the raw text.

3. Failure Handling – If parsing fails, a FormatError bubbles up. The resolver catches this and either:

   • Re-raises a ResolverParsingError (subclass of LangExtractError from langextract/core/exceptions.py) when suppress_parse_errors=False (default).
   • Suppresses the error, logs the exception, and returns an empty list when suppress_parse_errors=True.

Configuring Error Suppression with suppress_parse_errors

The suppress_parse_errors parameter controls whether parse failures terminate execution or allow the pipeline to continue.

Default Behavior (Strict Mode)

By default, suppress_parse_errors is False. Any malformed LLM output raises a ResolverParsingError:

from langextract.resolver import Resolver, ResolverParsingError

resolver = Resolver()
raw_output = "not a valid json"

try:
    extractions = resolver.resolve(raw_output)
except ResolverParsingError as e:
    print(f"Parsing failed: {e}")
    # Handle the error or abort processing

Suppressed Mode (Resilient Processing)

Set suppress_parse_errors=True to log errors and continue with an empty extraction list:

resolver = Resolver()
raw_output = "malformed yaml: - item 1  - item 2"  # Invalid formatting

extractions = resolver.resolve(raw_output, suppress_parse_errors=True)

# Returns [] and logs the error via absl.logging

print(f"Extracted {len(extractions)} items")  # Extracted 0 items

Using the High-Level extract() API

When using the high-level extract() function in langextract/extraction.py, pass suppress_parse_errors through the resolver_params dictionary:

from langextract import extraction

# Resilient batch processing

results = extraction.extract(
    text_or_documents=["Document 1", "Document 2"],
    prompt_description="Extract company names.",
    examples=[{"text": "Apple Inc.", "extraction": [{"name": "Apple Inc."}]}],
    resolver_params={"suppress_parse_errors": True},
)

# Failed parses are logged and skipped; successful extractions are returned

For strict validation during testing or when data quality is critical, explicitly disable suppression:

results = extraction.extract(
    text_or_documents=critical_documents,
    prompt_description="Extract financial figures.",
    examples=financial_examples,
    resolver_params={"suppress_parse_errors": False},  # Explicit strict mode

)

# Any parse failure raises ResolverParsingError immediately

Logging and Debugging Parse Failures

When suppress_parse_errors=True, LangExtract logs detailed failure information via absl.logging.exception at the ERROR level. The log entry includes:

• The raw input_text that failed to parse
• The underlying FormatError message and stack trace

This logging occurs in langextract/resolver.py (lines 65-71) within the exception handling block:

# Example of what appears in logs when suppression is enabled:

# ERROR:langextract.resolver:Failed to parse model output

# Traceback (most recent call last):

#   ...

# FormatError: Expecting ',' delimiter: line 1 column 15 (char 14)

# Input text: {"name": "John" "age": 30}

To capture these failures programmatically while still suppressing exceptions, configure an absl.logging handler or monitor the return value (empty list indicates a suppressed parse failure).

Impact on Downstream Alignment

Suppressing parse errors affects the subsequent alignment step. When Resolver.resolve() returns an empty list due to a suppressed error, the Resolver.align() method (also in langextract/resolver.py) receives no extractions to process.

This causes the alignment step to exit early without performing token-level matching between the extractions and the source text. Consequently:

• No alignment warnings are generated for the failed chunk
• The pipeline continues to the next document or chunk without spurious error messages
• Processing overhead is reduced for unparseable outputs

Summary

• Primary exception: ResolverParsingError (subclass of LangExtractError) raised when LLM output cannot be parsed into structured extractions.
• Suppression mechanism: Set suppress_parse_errors=True in Resolver.resolve() or pass it via resolver_params in extraction.extract() to log errors and return empty lists instead of raising exceptions.
• Logging behavior: Suppressed errors are logged at ERROR level via absl.logging.exception, including the raw input text and FormatError details.
• Alignment impact: Suppressed parse failures return empty extraction lists, causing the alignment step to skip processing for that chunk.
• Use cases: Enable suppression for resilient batch processing with unreliable models; disable it for strict data quality requirements or debugging prompt issues.

Frequently Asked Questions

What exception does LangExtract raise when parsing fails?

LangExtract raises ResolverParsingError, which is a subclass of LangExtractError defined in langextract/core/exceptions.py. This exception wraps the underlying FormatError from langextract/core/format_handler.py and indicates that the language model's output could not be parsed into valid Extraction objects.

How do I prevent LangExtract from stopping on parse errors?

Pass suppress_parse_errors=True either directly to Resolver.resolve() or within the resolver_params dictionary when calling extraction.extract(). When enabled, the library catches parsing exceptions, logs them via absl.logging.exception, and returns an empty list instead of raising ResolverParsingError, allowing your pipeline to continue processing remaining documents.

Where does LangExtract log suppressed parse errors?

Suppressed parse errors are logged at the ERROR level using absl.logging.exception within the exception handling block in langextract/resolver.py (lines 65-71). The log entry includes the full stack trace of the underlying FormatError and the raw input_text that failed to parse, enabling you to audit which specific model outputs caused failures.

Does suppressing parse errors affect the alignment step?

Yes. When a parse error is suppressed, Resolver.resolve() returns an empty list of extractions. Consequently, the downstream alignment step (Resolver.align()) receives no extractions to process and exits early without performing token-level matching. This prevents spurious alignment warnings and reduces processing overhead for unparseable chunks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}