unclecode/crawl4ai · error · ValueError

concurrency must be positive

Error message

concurrency must be positive

What it means

LinkPreviewConfig validates that concurrency is a positive number because it sizes the worker pool for concurrently fetching link previews. Zero or negative concurrency has no meaningful execution semantics, so construction fails immediately.

Source

Thrown at crawl4ai/async_configs.py:1199

            max_links: Maximum number of links to process (prevents overload)
            query: Query string for BM25 contextual scoring (optional)
            score_threshold: Minimum relevance score to include links (0.0-1.0, optional)
            verbose: Show detailed progress during extraction
        """
        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),

View on GitHub (pinned to 7e80152142)

Solutions

1. Set concurrency to a positive value; 5–20 is typical for link-preview fetching
2. If you meant to disable link previews, pass link_preview_config=None to CrawlerRunConfig instead of zeroing fields
3. Guard computed values: max(1, computed_concurrency)

Example fix

// before
cfg = LinkPreviewConfig(concurrency=workers - cores)  # can be <= 0
// after
cfg = LinkPreviewConfig(concurrency=max(1, workers - cores))

concurrency = max(1, int(concurrency or 5))
cfg = LinkPreviewConfig(concurrency=concurrency)

When it happens

Trigger: LinkPreviewConfig(concurrency=0), a negative value, or computing concurrency from a formula (e.g. desired_parallelism - existing) that evaluates to <= 0.

Common situations: Deriving concurrency from CPU count or a config file where the key is absent and defaults to 0; disabling previews by setting concurrency=0 instead of omitting the config.

Related errors

• timeout must be positive
• max_links 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/a70473b6b6698953. Report an issue: GitHub.