unclecode/crawl4ai · error · ValueError

max_links must be positive

Error message

max_links must be positive

What it means

LinkPreviewConfig requires max_links > 0 because it caps how many discovered links get previewed. Zero or negative max_links would make the feature a no-op with ambiguous intent, so it fails fast instead of silently skipping work.

Source

Thrown at crawl4ai/async_configs.py:1203

        """
        self.include_internal = include_internal
        self.include_external = include_external
        self.include_patterns = include_patterns
        self.exclude_patterns = exclude_patterns
        self.concurrency = concurrency
        self.timeout = timeout
        self.max_links = max_links
        self.query = query
        self.score_threshold = score_threshold
        self.verbose = verbose
        
        # Validation
        if concurrency <= 0:
            raise ValueError("concurrency must be positive")
        if timeout <= 0:
            raise ValueError("timeout must be positive")
        if max_links <= 0:
            raise ValueError("max_links must be positive")
        if score_threshold is not None and not (0.0 <= score_threshold <= 1.0):
            raise ValueError("score_threshold must be between 0.0 and 1.0")
        if not include_internal and not include_external:
            raise ValueError("At least one of include_internal or include_external must be True")
    
    @staticmethod
    def from_dict(config_dict: Dict[str, Any]) -> "LinkPreviewConfig":
        """Create LinkPreviewConfig from dictionary (for backward compatibility)."""
        if not config_dict:
            return None
        
        return LinkPreviewConfig(
            include_internal=config_dict.get("include_internal", True),
            include_external=config_dict.get("include_external", False),
            include_patterns=config_dict.get("include_patterns"),
            exclude_patterns=config_dict.get("exclude_patterns"),
            concurrency=config_dict.get("concurrency", 10),
            timeout=config_dict.get("timeout", 5),

View on GitHub (pinned to 7e80152142)

Solutions

1. Use a positive cap, e.g. LinkPreviewConfig(max_links=10)
2. To disable previews entirely, pass link_preview_config=None in CrawlerRunConfig
3. Clamp computed budgets: max(1, budget)

Example fix

// before
cfg = LinkPreviewConfig(max_links=0)  # attempt to disable
// after
run_cfg = CrawlerRunConfig(link_preview_config=None)  # actual way to disable

if not previews_wanted:
    run_cfg = CrawlerRunConfig(link_preview_config=None)
else:
    run_cfg = CrawlerRunConfig(link_preview_config=LinkPreviewConfig(max_links=max(1, budget)))

When it happens

Trigger: LinkPreviewConfig(max_links=0) or negative; computing max_links as total_budget - links_already_used and getting <= 0.

Common situations: Trying to disable link previews via max_links=0; dynamic budgets in scrapers that allocate zero links to some pages.

Related errors

• concurrency must be positive
• timeout must be positive
• score_threshold must be between 0.0 and 1.0
• At least one of include_internal or include_external must be
• link_preview_config must be LinkPreviewConfig object or dict

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