unclecode/crawl4ai · error · ValueError

Unsupported number of browsers: {num_browsers}

Error message

Unsupported number of browsers: {num_browsers}

What it means

ValueError from UserAgentGenerator's browser-stack builder: the requested num_browsers is not a key in browser_combinations (which supports stacks of 1-3 browsers). The generator composes realistic version strings by sampling from predefined combinations per count, so unsupported counts have no template.

Source

Thrown at crawl4ai/user_agent_generator.py:278

    def get_browser_stack(self, num_browsers: int = 1) -> List[str]:
        """
        Get a valid combination of browser versions.

        How it works:
        1. Check if the number of browsers is supported.
        2. Randomly choose a combination of browsers.
        3. Iterate through the combination and add browser versions.
        4. Return the browser stack.

        Args:
            num_browsers: Number of browser specifications (1-3)

        Returns:
            List[str]: A list of browser versions.
        """
        if num_browsers not in self.browser_combinations:
            raise ValueError(f"Unsupported number of browsers: {num_browsers}")

        combination = random.choice(self.browser_combinations[num_browsers])
        browser_stack = []

        for browser in combination:
            if browser == "chrome":
                browser_stack.append(random.choice(self.chrome_versions))
            elif browser == "firefox":
                browser_stack.append(random.choice(self.firefox_versions))
            elif browser == "safari":
                browser_stack.append(random.choice(self.safari_versions))
            elif browser == "edge":
                browser_stack.append(random.choice(self.edge_versions))
            elif browser == "gecko":
                browser_stack.append(random.choice(self.rendering_engines["gecko"]))
            elif browser == "webkit":
                browser_stack.append(self.rendering_engines["chrome_webkit"])

View on GitHub (pinned to 7e80152142)

Solutions

1. Clamp the value to 1-3 before calling: max(1, min(3, num_browsers)).
2. If you need richer fingerprint variety, vary OS/device and version lists instead of stack depth.
3. Check the generator's API/docs for the supported range and pass a literal.

Example fix

# before
ua = generator.generate_user_agent(num_browsers=4)  # ValueError: Unsupported number of browsers: 4

# after
num = max(1, min(3, requested_count))
ua = generator.generate_user_agent(num_browsers=num)

def safe_num_browsers(n: int | None) -> int:
    if n is None:
        return 2
    return max(1, min(3, int(n)))

try:
    ua = generator.generate_user_agent(num_browsers=n)
except ValueError as e:
    if 'Unsupported number of browsers' in str(e):
        ua = generator.generate_user_agent(num_browsers=max(1, min(3, n)))

When it happens

Trigger: Calling _get_browser_stack (or a public wrapper like generate_user_agent with a stack size parameter) with num_browsers of 0, a negative number, or >= 4.

Common situations: Computing the count dynamically (e.g. random.randint(1, 5) or len(custom_list)) and letting it exceed 3, passing a list length instead of a clamped int, or API misuse assuming any count is supported.

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/d41b79ea7db5b1cf. Report an issue: GitHub.