unclecode/crawl4ai · error · ValueError

chunking_strategy must be an instance of ChunkingStrategy

Error message

chunking_strategy must be an instance of ChunkingStrategy

What it means

CrawlerRunConfig validation: chunking_strategy must be an instance of ChunkingStrategy (e.g. RegexChunking, HtmlChunking) or None. It is used internally for content splitting before extraction; wrong types fail fast here rather than mid-crawl.

Source

Thrown at crawl4ai/async_configs.py:1847

        # Robots.txt Handling Parameters
        self.check_robots_txt = check_robots_txt

        # User Agent Parameters
        self.user_agent = user_agent
        self.user_agent_mode = user_agent_mode
        self.user_agent_generator_config = user_agent_generator_config

        # Validate type of extraction strategy and chunking strategy if they are provided
        if self.extraction_strategy is not None and not isinstance(
            self.extraction_strategy, ExtractionStrategy
        ):
            raise ValueError(
                "extraction_strategy must be an instance of ExtractionStrategy"
            )
        if self.chunking_strategy is not None and not isinstance(
            self.chunking_strategy, ChunkingStrategy
        ):
            raise ValueError(
                "chunking_strategy must be an instance of ChunkingStrategy"
            )
        if self.markdown_generator is not None and not isinstance(
            self.markdown_generator, MarkdownGenerationStrategy
        ):
            hint = ""
            if isinstance(self.markdown_generator, dict):
                hint = (
                    ' The JSON format must be {"type": "<ClassName>", "params": {...}}.'
                    ' Note: "params" is required — "options" or other keys are not recognized.'
                )
            raise ValueError(
                "markdown_generator must be an instance of MarkdownGenerationStrategy, "
                f"got {type(self.markdown_generator).__name__}.{hint}"
            )

        # Set default chunking strategy if None
        if self.chunking_strategy is None:

View on GitHub (pinned to 7e80152142)

Solutions

1. Instantiate: chunking_strategy=RegexChunking()
2. Or omit it — None gets replaced by the default RegexChunking()
3. For dict configs use {'type': 'RegexChunking', 'params': {...}} with CrawlerRunConfig.from_kwargs

Example fix

// before
cfg = CrawlerRunConfig(chunking_strategy=RegexChunking)  # class, not instance
// after
cfg = CrawlerRunConfig(chunking_strategy=RegexChunking())

from crawl4ai.chunking_strategy import ChunkingStrategy

if not isinstance(chunking_strategy, ChunkingStrategy):
    chunking_strategy = None  # default RegexChunking() is applied

from crawl4ai.chunking_strategy import ChunkingStrategy

def is_chunking_strategy(v) -> bool:
    return v is None or isinstance(v, ChunkingStrategy)

When it happens

Trigger: Passing chunking_strategy="RegexChunking", a dict, or the class object RegexChunking instead of RegexChunking().

Common situations: JSON-driven configuration pipelines that pass strings; noting that if you pass None a default RegexChunking() is assigned for you.

Related errors

• extraction_strategy must be an instance of ExtractionStrateg
• link_preview_config must be LinkPreviewConfig object or dict
• virtual_scroll_config must be VirtualScrollConfig object or
• [NSTProxy] Invalid protocol: {protocol}
• concurrency must be positive

AI-assisted analysis of unclecode/crawl4ai@7e80152142 (2026-08-14). Data as JSON: /api/errors/68d9ac0eadc8b811. Report an issue: GitHub.