Unknown extraction mode '{string}'. Supported modes are: {li

Error message

Unknown extraction mode '{string}'. Supported modes are: {list(enum_map.keys())}

What it means

PyPDFExtractionMode.from_str converts a user-supplied string into a PyPDFExtractionMode enum by looking it up in a value-keyed map. If the string does not exactly match one of the enum's values, a ValueError listing the valid modes is raised. This guards the PyPDFToDocument component against invalid extraction-mode configuration at pipeline-construction time.

Source

Thrown at haystack/components/converters/pypdf.py:46

    PLAIN = "plain"
    LAYOUT = "layout"

    def __str__(self) -> str:
        """
        Convert a PyPDFExtractionMode enum to a string.
        """
        return self.value

    @staticmethod
    def from_str(string: str) -> "PyPDFExtractionMode":
        """
        Convert a string to a PyPDFExtractionMode enum.
        """
        enum_map = {e.value: e for e in PyPDFExtractionMode}
        mode = enum_map.get(string)
        if mode is None:
            msg = f"Unknown extraction mode '{string}'. Supported modes are: {list(enum_map.keys())}"
            raise ValueError(msg)
        return mode


@component
class PyPDFToDocument:
    """
    Converts PDF files to documents your pipeline can query.

    This component uses the PyPDF library.
    You can attach metadata to the resulting documents.

    ### Usage example

    ```python
    from haystack.components.converters.pypdf import PyPDFToDocument
    from datetime import datetime

    converter = PyPDFToDocument()

View on GitHub (pinned to e318778c9b)

Solutions

Check the exact supported values in the message (e.g. ['plain','layout']) and use one verbatim, lowercase.
If using PyPDFToDocument, pass extraction_mode='plain' or 'layout' exactly as documented.
If the mode name came from an old pipeline YAML, update the config to the current enum value.

Example fix

# before
converter = PyPDFToDocument(extraction_mode="text")
# after
from haystack.components.converters.pypdf import PyPDFExtractionMode
converter = PyPDFToDocument(extraction_mode="layout")  # or PyPDFExtractionMode.LAYOUT

Defensive patterns

Strategy: validation

Validate before calling

from haystack.components.converters.pypdf import PyPDFExtractionMode

def is_valid_mode(mode: str) -> bool:
    return mode in {e.value for e in PyPDFExtractionMode}

assert is_valid_mode(extraction_mode), f"{extraction_mode!r} not in {sorted(e.value for e in PyPDFExtractionMode)}"

Type guard

from typing import Literal
from haystack.components.converters.pypdf import PyPDFExtractionMode

ModeLiteral = Literal[tuple(PyPDFExtractionMode.__members__)]  # ('plain', 'layout')

def is_extraction_mode(s: str) -> bool:
    return s in {e.value for e in PyPDFExtractionMode}

Try / catch

try:
    converter = PyPDFToDocument(extraction_mode=mode)
except ValueError as e:
    logger.error("Bad extraction_mode %s: %s", mode, e)
    converter = PyPDFToDocument()  # default 'plain'

Prevention

Keep mode strings centralized as PyPDFExtractionMode enum members instead of raw strings
Enable mypy Literal typing on config loaders to catch typos before runtime
Add a unit test that parses your pipeline YAML and constructs every component

When it happens

Trigger: Passing a string to PyPDFExtractionMode.from_str (or the extraction_mode init/run parameter of PyPDFToDocument, which resolves through it) that is not an exact match for an enum value, e.g. 'plain_text', 'text', or 'TEXT' instead of 'plain'.

Common situations: Typo in YAML/JSON pipeline config; using an outdated mode name after an enum value change; assuming case-insensitive lookup (lookup is case-sensitive); copying examples from older haystack versions.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/21e09ac0404f535d. Report an issue: GitHub.