# How to Handle Extraction Errors and Parse Failures in LangExtract

> Learn to handle LangExtract errors and parse failures. Use suppress_parse_errors or catch ResolverParsingError for robust LLM output processing.

- Repository: [Google/langextract](https://github.com/google/langextract)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/google/langextract/blob/main/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`](https://github.com/google/langextract/blob/main/langextract/resolver.py) (lines 45-50).

2. **Parsing Attempt** – The `Resolver.resolve()` method delegates to `FormatHandler.parse_output()` in [`langextract/core/format_handler.py`](https://github.com/google/langextract/blob/main/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`](https://github.com/google/langextract/blob/main/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`:

```python
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:

```python
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`](https://github.com/google/langextract/blob/main/langextract/extraction.py), pass `suppress_parse_errors` through the `resolver_params` dictionary:

```python
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:

```python
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`](https://github.com/google/langextract/blob/main/langextract/resolver.py) (lines 65-71) within the exception handling block:

```python

# 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`](https://github.com/google/langextract/blob/main/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`](https://github.com/google/langextract/blob/main/langextract/core/exceptions.py). This exception wraps the underlying `FormatError` from [`langextract/core/format_handler.py`](https://github.com/google/langextract/blob/main/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`](https://github.com/google/langextract/blob/main/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.