run-llama/llama_index · error · ValueError

Metadata length ({metadata_len}) is longer than chunk size (

Error message

Metadata length ({metadata_len}) is longer than chunk size ({self.chunk_size}). Consider increasing the chunk size or decreasing the size of your metadata to avoid this.

What it means

Error "Metadata length ({metadata_len}) is longer than chunk size ({self.chunk_size}). Consider increasing the chunk size or decreasing the size of your metadata to avoid this." thrown in run-llama/llama_index.

Source

Thrown at llama-index-core/llama_index/core/node_parser/text/sentence.py:160

            chunk_overlap=chunk_overlap,
            tokenizer=tokenizer,
            paragraph_separator=paragraph_separator,
            chunking_tokenizer_fn=chunking_tokenizer_fn,
            secondary_chunking_regex=secondary_chunking_regex,
            callback_manager=callback_manager,
            include_metadata=include_metadata,
            include_prev_next_rel=include_prev_next_rel,
        )

    @classmethod
    def class_name(cls) -> str:
        return "SentenceSplitter"

    def split_text_metadata_aware(self, text: str, metadata_str: str) -> List[str]:
        metadata_len = len(self._tokenizer(metadata_str))
        effective_chunk_size = self.chunk_size - metadata_len
        if effective_chunk_size <= 0:
            raise ValueError(
                f"Metadata length ({metadata_len}) is longer than chunk size "
                f"({self.chunk_size}). Consider increasing the chunk size or "
                "decreasing the size of your metadata to avoid this."
            )
        elif effective_chunk_size < 50:
            print(
                f"Metadata length ({metadata_len}) is close to chunk size "
                f"({self.chunk_size}). Resulting chunks are less than 50 tokens. "
                "Consider increasing the chunk size or decreasing the size of "
                "your metadata to avoid this.",
                flush=True,
            )

        return self._split_text(text, chunk_size=effective_chunk_size)

    def split_text(self, text: str) -> List[str]:
        return self._split_text(text, chunk_size=self.chunk_size)

View on GitHub (pinned to afd0fef371)

Solutions

1. Increase chunk_size so metadata plus content fits.
2. Reduce metadata size or set metadata to be excluded from the chunk length calculation.

When it happens

Trigger: Thrown at llama-index-core/llama_index/core/node_parser/text/sentence.py:160 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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