unclecode/crawl4ai · error · ValueError

Invalid proxy string format: {proxy_str}

Error message

Invalid proxy string format: {proxy_str}

What it means

ValueError from ProxyConfig.from_string (via the static parser) when the proxy string does not split into the expected number of colon-separated parts. The parser accepts 'ip:port', 'user:pass@ip:port', and 'user:pass@ip:port:extra' shapes; any other part count (0, 1, 4+) is rejected with this message.

Source

Thrown at crawl4ai/proxy_strategy.py:67

    def from_string(proxy_str: str) -> "ProxyConfig":
        """Create a ProxyConfig from a string in the format 'ip:port:username:password'."""
        parts = proxy_str.split(":")
        if len(parts) == 4:  # ip:port:username:password
            ip, port, username, password = parts
            return ProxyConfig(
                server=f"http://{ip}:{port}",
                username=username,
                password=password,
                ip=ip
            )
        elif len(parts) == 2:  # ip:port only
            ip, port = parts
            return ProxyConfig(
                server=f"http://{ip}:{port}",
                ip=ip
            )
        else:
            raise ValueError(f"Invalid proxy string format: {proxy_str}")
    
    @staticmethod
    def from_dict(proxy_dict: Dict) -> "ProxyConfig":
        """Create a ProxyConfig from a dictionary."""
        return ProxyConfig(
            server=proxy_dict.get("server"),
            username=proxy_dict.get("username"),
            password=proxy_dict.get("password"),
            ip=proxy_dict.get("ip")
        )
    
    @staticmethod
    def from_env(env_var: str = "PROXIES") -> List["ProxyConfig"]:
        """Load proxies from environment variable.
        
        Args:
            env_var: Name of environment variable containing comma-separated proxy strings
            

View on GitHub (pinned to 7e80152142)

Solutions

1. Strip the scheme: use '1.2.3.4:8080' or 'user:pass@1.2.3.4:8080' — no 'http://' prefix (the parser adds it).
2. For passwords containing colons, URL-encode the password (%3A) or use ProxyConfig.from_dict / construct ProxyConfig directly with server/username/password fields.
3. For IPv6 proxies, construct ProxyConfig directly instead of the string parser.
4. Validate the string with a quick split test before feeding it to the crawler config.

Example fix

# before
proxy = ProxyConfig.from_string("http://user:pass@1.2.3.4:8080")  # ValueError: Invalid proxy string format

# after
proxy = ProxyConfig.from_string("user:pass@1.2.3.4:8080")
# or, for messy credentials:
proxy = ProxyConfig.from_dict({"server": "http://1.2.3.4:8080", "username": "user", "password": "p:a:s:s"})

def valid_proxy_string(s: str) -> bool:
    import re
    # schemeless user:pass@host:port or host:port, IPv4 only
    return bool(re.fullmatch(r"(?:[\w.%+-]+:[\w.%+-]+@)?\d{1,3}(?:\.\d{1,3}){3}:\d{1,5}", s))

try:
    proxy = ProxyConfig.from_string(raw_proxy)
except ValueError as e:
    if 'Invalid proxy string' in str(e):
        proxy = ProxyConfig.from_dict({"server": f"http://{parsed_host}:{parsed_port}", "username": u, "password": p})

When it happens

Trigger: Passing a malformed proxy string such as 'http://1.2.3.4:8080' (scheme prefix adds parts), '1.2.3.4' (no port), 'a:b:c:d:e' (too many), or one containing stray colons in the password when using more parts than supported.

Common situations: Copy-pasting a proxy URL with an http:// scheme from a provider dashboard, environment-variable proxy strings from third-party services, passwords containing colons, or IPv6 addresses (multiple colons) breaking the naive split.

Related errors

• [NSTProxy] Invalid protocol: {protocol}
• [NSTProxy] token and channel_id are required
• concurrency must be positive
• timeout must be positive
• max_links must be positive

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