Unknown link format '{string}'. Supported formats are: {list

Error message

Unknown link format '{string}'. Supported formats are: {list(enum_map.keys())}

What it means

LinkFormat.from_str converts a string into a LinkFormat enum used by converter utilities. The lookup lowercases the input but otherwise requires it to exactly equal one of the enum's values; otherwise a ValueError with the supported list is raised. It validates the link_format option of converters that render HTML links.

Source

Thrown at haystack/components/converters/utils.py:34

    """

    MARKDOWN = "markdown"
    PLAIN = "plain"
    NONE = "none"

    def __str__(self) -> str:
        return self.value

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


def get_bytestream_from_source(source: str | Path | ByteStream, guess_mime_type: bool = False) -> ByteStream:
    """
    Creates a ByteStream object from a source.

    :param source:
        A source to convert to a ByteStream. Can be a string (path to a file), a Path object, or a ByteStream.
    :param guess_mime_type:
        Whether to guess the mime type from the file.
    :return:
        A ByteStream object.
    """

    if isinstance(source, ByteStream):
        return source
    if isinstance(source, (str, Path)):

View on GitHub (pinned to e318778c9b)

Solutions

Use exactly one of the supported formats listed in the message (lowercase accepted due to .lower(), but the word must match).
Inspect LinkFormat's values with [e.value for e in LinkFormat] to see the valid set.
If the intent was table output format, that is a separate parameter (table_format) — set that instead.

Example fix

# before
converter.component.link_format = "md"
# after
converter.component.link_format = "markdown"

Defensive patterns

Strategy: validation

Validate before calling

from haystack.components.converters.utils import LinkFormat

def is_valid_link_format(fmt: str) -> bool:
    return fmt.lower() in {e.value for e in LinkFormat}

assert is_valid_link_format(link_format), f"{link_format!r} not in {sorted(e.value for e in LinkFormat)}"

Type guard

from haystack.components.converters.utils import LinkFormat

def is_link_format(s: str) -> bool:
    return s.lower() in {e.value for e in LinkFormat}

Try / catch

try:
    converter.run(sources=srcs, link_format=fmt)
except ValueError as e:
    logger.warning("Falling back to default link format: %s", e)
    converter.run(sources=srcs)

Prevention

Use LinkFormat.from_str() at config boundaries so errors surface early with the valid list
Store link_format in your pipeline YAML exactly as the enum values are spelled
Write a smoke test that instantiates all components from your config at CI time

When it happens

Trigger: Passing a string (directly via from_str or via a component's link_format parameter resolved through it) that is not one of the LinkFormat values, e.g. 'url', 'href', or 'md' instead of a supported value like 'markdown'/'plain'/'none'.

Common situations: Typo or wrong concept in pipeline YAML (confusing link format with table format); inventing a format name; migrating from a component that accepted different strings.

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/c9805ff40b357823. Report an issue: GitHub.