unclecode/crawl4ai · error · ValueError

score_threshold must be between 0.0 and 1.0

Error message

score_threshold must be between 0.0 and 1.0

What it means

LinkPreviewConfig accepts an optional score_threshold used to filter links by relevance (e.g. cosine similarity against query). Valid values are a fraction between 0.0 and 1.0; anything outside is rejected because the comparison would be meaningless.

Source

Thrown at crawl4ai/async_configs.py:1205

        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),
            max_links=config_dict.get("max_links", 100),
            query=config_dict.get("query"),

View on GitHub (pinned to 7e80152142)

Solutions

1. Pass a fraction in [0.0, 1.0], e.g. score_threshold=0.7
2. If your config stores percentages, divide by 100 before constructing
3. Leave it None to disable relevance filtering

Example fix

// before
cfg = LinkPreviewConfig(query="docs", score_threshold=70)
// after
cfg = LinkPreviewConfig(query="docs", score_threshold=0.7)

if score_threshold is not None:
    score_threshold = float(score_threshold)
    if score_threshold > 1:  # assume percentage
        score_threshold /= 100.0
    assert 0.0 <= score_threshold <= 1.0, "score_threshold must be in [0,1]"

def valid_threshold(t) -> bool:
    return t is None or (isinstance(t, (int, float)) and 0.0 <= t <= 1.0)

When it happens

Trigger: score_threshold=5, -0.1, 1.5, or passing a percentage (e.g. 70 meaning 70%) instead of a fraction.

Common situations: Porting thresholds expressed as percentages from other tools; env/config values scaled 0–100.

Related errors

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