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

ValueError from CrawlerRunConfig.__init__: chunking_strategy was supplied but is not an instance of ChunkingStrategy (and not None). If None, RegexChunking() is installed as the default right after this check.

Source

Thrown at crawl4ai/async_configs.py:1847:1015

        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"
            )

        # Set default chunking strategy if None
        if self.chunking_strategy is None:
            self.chunking_strategy = RegexChunking()

        # Deep Crawl Parameters
        self.deep_crawl_strategy = deep_crawl_strategy
        
        # Experimental Parameters
        self.experimental = experimental or {}


    def __getattr__(self, name):
        """Handle attribute access."""
        if name in self._UNWANTED_PROPS:
            raise AttributeError(f"Getting '{name}' is deprecated. {self._UNWANTED_PROPS[name]}")
        raise AttributeError(f"'{self.__class__.__name__}' has no attribute '{name}'")

View on GitHub (pinned to 7e80152142)

Solutions

1. Instantiate the strategy: chunking_strategy=RegexChunking() or NlpSentenceChunking()
2. Custom chunkers must subclass ChunkingStrategy and implement chunk()/__repr__
3. If unsure, omit the parameter - RegexChunking is the default

Example fix

# before
config = CrawlerRunConfig(chunking_strategy=RegexChunking)

# after
from crawl4ai import RegexChunking
config = CrawlerRunConfig(chunking_strategy=RegexChunking())

from crawl4ai.chunking_strategy import ChunkingStrategy
assert chunking_strategy is None or isinstance(chunking_strategy, ChunkingStrategy), "chunking_strategy must be a ChunkingStrategy instance"

from crawl4ai.chunking_strategy import ChunkingStrategy

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

try:
    config = CrawlerRunConfig(chunking_strategy=chunker)
except ValueError:
    config = CrawlerRunConfig(chunking_strategy=RegexChunking())  # sane default

When it happens

Trigger: CrawlerRunConfig(chunking_strategy='regex'), chunking_strategy=RegexChunking (class not instance), or a custom chunker not subclassing ChunkingStrategy.

Common situations: Setting chunking only because an LLM extraction strategy needs chunks, and passing the class by mistake; copying tutorial code that omitted parentheses; providing a plain function expecting it to be used as a chunker.

Related errors

• extraction_strategy must be an instance of ExtractionStrateg
• chunking_strategy must be an instance of ChunkingStrategy
• Invalid source(s): {invalid}. Valid: {VALID_SOURCES}
• Hook '{hook_name}' must be a callable function, got {type(ho
• too many hooks (max 10)

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