deepset-ai/haystack · error · ValueError

Unknown join mode '{string}'. Supported modes in DocumentJoi

Error message

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

What it means

JoinMode.from_str converts a string join mode into the JoinMode enum used by DocumentJoiner. It raises ValueError when the string does not match any enum value ('concatenate', 'merge', 'reciprocal_rank_fusion', 'split_documents').

Source

Thrown at haystack/components/joiners/document_joiner.py:41

    CONCATENATE = "concatenate"
    MERGE = "merge"
    RECIPROCAL_RANK_FUSION = "reciprocal_rank_fusion"
    DISTRIBUTION_BASED_RANK_FUSION = "distribution_based_rank_fusion"

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

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


@component
class DocumentJoiner:
    """
    Joins multiple lists of documents into a single list.

    It supports different join modes:
    - concatenate: Keeps the highest-scored document in case of duplicates.
    - merge: Calculates a weighted sum of scores for duplicates and merges them.
    - reciprocal_rank_fusion: Merges and assigns scores based on reciprocal rank fusion.
    - distribution_based_rank_fusion: Merges and assigns scores based on scores distribution in each Retriever.

    ### Usage example:

    ```python
    from haystack import Pipeline, Document

View on GitHub (pinned to e318778c9b)

Solutions

Use one of the exact enum values: print([e.value for e in JoinMode]) to list them.
Import the enum and pass it directly: from haystack.components.joiners import JoinMode; DocumentJoiner(join_mode=JoinMode.RECIPROCAL_RANK_FUSION).
Fix casing/typos to match the lowercase enum value exactly.

Example fix

// before
DocumentJoiner(join_mode="rrf")
// after
from haystack.components.joiners import JoinMode
DocumentJoiner(join_mode=JoinMode.RECIPROCAL_RANK_FUSION)  # or "reciprocal_rank_fusion"

Defensive patterns

Strategy: validation

Validate before calling

from haystack.components.joiners.document_joiner import JoinMode
VALID = {e.value for e in JoinMode}
assert mode in VALID, f"join_mode must be one of {sorted(VALID)}, got {mode!r}"

Type guard

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

Try / catch

try:
    joiner = DocumentJoiner(join_mode=mode)
except ValueError as e:
    logger.error("bad join_mode %r: %s", mode, e)
    joiner = DocumentJoiner(join_mode=JoinMode.CONCATENATE)

Prevention

Pass the JoinMode enum member instead of a raw string
Copy the exact lowercase value ('reciprocal_rank_fusion', not 'rrf')
Check the error message: it lists all supported modes

When it happens

Trigger: Passing DocumentJoiner(join_mode='rrf'), join_mode='CONCATENATE' (uppercase), or any misspelled/unsupported mode string to the constructor or anywhere JoinMode.from_str is called.

Common situations: Typos or shorthand ('rrf' instead of 'reciprocal_rank_fusion'); wrong casing; copying a mode name from a different library; version drift where a mode was added/renamed.

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