unclecode/crawl4ai · error · ValueError

extraction_strategy must be an instance of ExtractionStrateg

Error message

extraction_strategy must be an instance of ExtractionStrategy

What it means

CrawlerRunConfig.__post_init__-style validation: extraction_strategy must be an instance of ExtractionStrategy (e.g. JsonCssExtractionStrategy, LLMExtractionStrategy) or None. Strings, dicts, or arbitrary callables are rejected because the crawler invokes strategy-specific methods (extract, run) on it.

Source

Thrown at crawl4ai/async_configs.py:1841

        # Connection Parameters
        self.stream = stream
        self.prefetch = prefetch  # Prefetch mode: return only HTML + links
        self.process_in_browser = process_in_browser  # Force browser processing for raw:/file:// URLs
        self.method = method

        # 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(

View on GitHub (pinned to 7e80152142)

Solutions

1. Instantiate the strategy: extraction_strategy=JsonCssExtractionStrategy(schema)
2. If loading from a dict, use the {'type': 'ClassName', 'params': {...}} serialization format and from_serializable_dict / CrawlerRunConfig.from_kwargs which auto-deserializes it
3. Pass None (or omit) when you do not want an extraction strategy

Example fix

// before
cfg = CrawlerRunConfig(extraction_strategy="JsonCssExtractionStrategy")
// after
from crawl4ai import JsonCssExtractionStrategy
cfg = CrawlerRunConfig(extraction_strategy=JsonCssExtractionStrategy(schema=my_schema))

from crawl4ai.extraction_strategy import ExtractionStrategy

if isinstance(extraction_strategy, dict):
    extraction_strategy = CrawlerRunConfig.from_kwargs(
        {"extraction_strategy": extraction_strategy}
    ).extraction_strategy

from crawl4ai.extraction_strategy import ExtractionStrategy

def is_extraction_strategy(v) -> bool:
    return v is None or isinstance(v, ExtractionStrategy)

try:
    CrawlerRunConfig(extraction_strategy=v)
except ValueError as e:
    if "extraction_strategy" in str(e):
        v = deserialize_strategy(v)  # {'type','params'} -> instance
    else:
        raise

When it happens

Trigger: Passing extraction_strategy="JsonCssExtractionStrategy" (class name string), a raw dict schema, or an uninitialized class reference instead of an instance.

Common situations: Loading config from JSON/YAML and passing it through unserialized; copy-pasting docs that show the class rather than an instance; confusion between class and instance.

Related errors

• chunking_strategy must be an instance of ChunkingStrategy
• 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/218bc003bf2cf2bd. Report an issue: GitHub.