unclecode/crawl4ai · error · ValueError

markdown_generator must be an instance of MarkdownGeneration

Error message

markdown_generator must be an instance of MarkdownGenerationStrategy, got {type(self.markdown_generator).__name__}.{hint}

What it means

CrawlerRunConfig validation: markdown_generator must be an instance of MarkdownGenerationStrategy (e.g. DefaultMarkdownGenerator) or None. The error message includes the received type name and, when a dict was passed, a hint about the exact JSON shape expected — the dict must use "type" and "params" keys, and "params" is required even when empty.

Source

Thrown at crawl4ai/async_configs.py:1859

            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:
            self.chunking_strategy = RegexChunking()

        # Deep Crawl Parameters
        self.deep_crawl_strategy = deep_crawl_strategy
        
        # Link Extraction Parameters
        if link_preview_config is None:
            self.link_preview_config = None
        elif isinstance(link_preview_config, LinkPreviewConfig):
            self.link_preview_config = link_preview_config
        elif isinstance(link_preview_config, dict):
            # Convert dict to config object for backward compatibility

View on GitHub (pinned to 7e80152142)

Solutions

1. For dict input use: {"type": "DefaultMarkdownGenerator", "params": {}} — 'params' is required; 'options' is not recognized
2. Or pass an instance: markdown_generator=DefaultMarkdownGenerator()
3. Route raw dicts through CrawlerRunConfig.from_kwargs, which auto-deserializes the {'type','params'} format

Example fix

// before
markdown_generator={"type": "DefaultMarkdownGenerator", "options": {...}}
// after
markdown_generator={"type": "DefaultMarkdownGenerator", "params": {"content_filter": {...}}}

if isinstance(markdown_generator, dict):
    assert set(markdown_generator) <= {"type", "params"}, "use only 'type' and 'params' keys"
    markdown_generator.setdefault("params", {})

from crawl4ai.markdown_generation_strategy import MarkdownGenerationStrategy

def is_markdown_generator(v) -> bool:
    return v is None or isinstance(v, MarkdownGenerationStrategy)

When it happens

Trigger: Passing markdown_generator={"type": "DefaultMarkdownGenerator", "options": {...}} (the rejected 'options' key), a string class name, or another object type.

Common situations: Deserializing configs from JSON (API server, dump()/load() roundtrip) with an older or hand-written format that used "options" instead of "params".

Related errors

• [NSTProxy] Invalid protocol: {protocol}
• concurrency must be positive
• timeout must be positive
• max_links must be positive
• score_threshold must be between 0.0 and 1.0

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