run-llama/llama_index · error · ValueError

Unknown oversized document strategy: {strategy}

Error message

Unknown oversized document strategy: {strategy}

What it means

Raised by DocumentContextExtractor._process_document when oversized_document_strategy is not one of the three recognized values ('warn', 'error', 'ignore') and an oversized document is encountered. The strategy string is compared case-sensitively with no normalization, so any misspelling or wrong casing reaches the else-branch and raises.

Source

Thrown at llama-index-core/llama_index/core/extractors/document_context.py:285

        # then truncate if necessary.
        if self.max_context_length is not None:
            strategy = self.oversized_document_strategy
            token_count = self._count_tokens(doc.get_content())
            if token_count > self.max_context_length:
                message = (
                    f"Document {doc.node_id} is too large ({token_count} tokens) "
                    f"to be processed. Doc metadata: {doc.metadata}"
                )

                if strategy == "warn":
                    logging.warning(message)
                elif strategy == "error":
                    raise ValueError(message)
                elif strategy == "ignore":
                    pass
                else:
                    raise ValueError(f"Unknown oversized document strategy: {strategy}")

        return doc

    async def aextract(self, nodes: Sequence[BaseNode]) -> List[Dict]:
        """
        Extract context for multiple nodes asynchronously, optimized for loosely ordered nodes.
        Processes each node independently without guaranteeing sequential document handling.
        Nodes will be *mostly* processed in document-order assuming nodes get passed in document-order.

        Args:
            nodes: List of nodes to process, ideally grouped by source document

        Returns:
            List of metadata dictionaries with generated context

        """
        metadata_list: List[Dict] = []
        for _ in nodes:

View on GitHub (pinned to afd0fef371)

Solutions

1. Use exactly one of: 'warn', 'error', 'ignore' (lowercase).
2. Validate the strategy at construction time in your own wrapper so the failure surfaces before any document is processed.
3. Check the DocumentContextExtractor signature/docs of your installed version for renamed values.

Example fix

# before
extractor = DocumentContextExtractor(oversized_document_strategy="raise")

# after
extractor = DocumentContextExtractor(oversized_document_strategy="error")

VALID_STRATEGIES = {"warn", "error", "ignore"}
strategy = config.get("oversized_document_strategy", "warn")
if strategy not in VALID_STRATEGIES:
    raise ValueError(f"strategy must be one of {sorted(VALID_STRATEGIES)}")

When it happens

Trigger: Passing oversized_document_strategy='raise', 'skip', 'ERROR', or None to DocumentContextExtractor, then feeding a document whose token count exceeds max_context_length (the check only runs for oversized docs, so misconfiguration stays latent until one arrives).

Common situations: Config-driven extractor construction from YAML where the enum values aren't documented; renaming the parameter across llama-index versions; using a variable that defaults to None instead of a valid strategy.

Related errors

• summaries must be one of ['self', 'prev', 'next']
• Invalid metric name: {metric}
• Cannot specify both similarity_fn and similarity_mode
• Document {doc.node_id} is too large ({token_count} tokens) t
• Extractor loading requires a class_name

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/e0e8144602a6b854. Report an issue: GitHub.