run-llama/llama_index · error · ValueError

Configured node parser does not have chunk overlap.

Error message

Configured node parser does not have chunk overlap.

What it means

Settings.chunk_overlap getter proxies to Settings.node_parser.chunk_overlap. If the installed node parser does not expose chunk_overlap (anything other than chunking splitters like SentenceSplitter/SentenceAwareNodeParser, or a custom parser without the attribute), the read raises this ValueError.

Source

Thrown at llama-index-core/llama_index/core/settings.py:177

            return self.node_parser.chunk_size
        else:
            raise ValueError("Configured node parser does not have chunk size.")

    @chunk_size.setter
    def chunk_size(self, chunk_size: int) -> None:
        """Set the chunk size."""
        if hasattr(self.node_parser, "chunk_size"):
            self.node_parser.chunk_size = chunk_size
        else:
            raise ValueError("Configured node parser does not have chunk size.")

    @property
    def chunk_overlap(self) -> int:
        """Get the chunk overlap."""
        if hasattr(self.node_parser, "chunk_overlap"):
            return self.node_parser.chunk_overlap
        else:
            raise ValueError("Configured node parser does not have chunk overlap.")

    @chunk_overlap.setter
    def chunk_overlap(self, chunk_overlap: int) -> None:
        """Set the chunk overlap."""
        if hasattr(self.node_parser, "chunk_overlap"):
            self.node_parser.chunk_overlap = chunk_overlap
        else:
            raise ValueError("Configured node parser does not have chunk overlap.")

    # ---- Node parser alias ----

    @property
    def text_splitter(self) -> NodeParser:
        """Get the text splitter."""
        return self.node_parser

    @text_splitter.setter
    def text_splitter(self, text_splitter: NodeParser) -> None:

View on GitHub (pinned to afd0fef371)

Solutions

1. Read chunk_overlap from the concrete splitter instance you constructed instead of from Settings.
2. Keep a chunking splitter installed if the proxy must work: Settings.node_parser = SentenceSplitter(chunk_size=512, chunk_overlap=50).
3. Guard reads with hasattr(Settings.node_parser, 'chunk_overlap') before accessing.
4. Expose chunk_overlap on custom NodeParser subclasses so the Settings contract keeps working.

Example fix

# before
Settings.node_parser = SentenceWindowNodeParser.from_defaults()
overlap = Settings.chunk_overlap  # ValueError

# after
Settings.node_parser = SentenceWindowNodeParser.from_defaults()
# keep a splitter reference for chunking parameters
_splitter = SentenceSplitter(chunk_size=512, chunk_overlap=50)
overlap = _splitter.chunk_overlap

from llama_index.core import Settings

def settings_chunk_overlap(default: int | None = None) -> int | None:
    parser = Settings.node_parser
    return parser.chunk_overlap if hasattr(parser, 'chunk_overlap') else default

def parser_has_chunk_overlap(parser) -> bool:
    return hasattr(parser, 'chunk_overlap')

try:
    ov = Settings.chunk_overlap
except ValueError:
    ov = 0  # non-chunking parser: no overlap concept

When it happens

Trigger: Reading Settings.chunk_overlap after setting Settings.node_parser to HierarchicalNodeParser, SentenceWindowNodeParser, MarkdownNodeParser, or a custom NodeParser; or a library reading the property to compute embedding-context defaults.

Common situations: Advanced ingestion strategies (hierarchical retrieval, sentence-window retrieval) replace the default splitter; later code that reads chunk_overlap for logging, validation, or downstream window sizing then blows up.

Related errors

• Configured node parser does not have chunk size.
• Metadata length ({metadata_len}) is longer than chunk size (
• EmptyIndex only supports response_mode=generation.
• Unknown retriever mode: {retriever_mode}
• Unknown retriever mode: {retriever_mode}

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