unclecode/crawl4ai · error · ValueError

[NSTProxy] Invalid protocol: {protocol}

Error message

[NSTProxy] Invalid protocol: {protocol}

What it means

Raised when set_nstproxy() receives a protocol other than "http" or "socks5". The protocol string is used verbatim to build the proxy server URL (protocol://ip:port), so only these two schemes are supported by NSTProxy's API.

Source

Thrown at crawl4ai/async_configs.py:1065

            token (str): NSTProxy API token.
            channel_id (str): NSTProxy channel ID.
            country (str, optional): Country code (default: "ANY").
            state (str, optional): State code (default: "").
            city (str, optional): City name (default: "").
            protocol (str, optional): Proxy protocol ("http" or "socks5"). Defaults to "http".
            session_duration (int, optional): Session duration in minutes (0 = rotate each request). Defaults to 10.

        Raises:
            ValueError: If the API response format is invalid.
            PermissionError: If the API returns an error message.
        """

        # --- Validate input early ---
        if not token or not channel_id:
            raise ValueError("[NSTProxy] token and channel_id are required")

        if protocol not in ("http", "socks5"):
            raise ValueError(f"[NSTProxy] Invalid protocol: {protocol}")

        # --- Build NSTProxy API URL ---
        params = {
            "fType": 2,
            "count": 1,
            "channelId": channel_id,
            "country": country,
            "protocol": protocol,
            "sessionDuration": session_duration,
            "token": token,
        }
        if state:
            params["state"] = state
        if city:
            params["city"] = city

        url = "https://api.nstproxy.com/api/v1/generate/apiproxies"

View on GitHub (pinned to 7e80152142)

Solutions

1. Use protocol="http" or protocol="socks5" exactly (lowercase)
2. If you need an HTTPS proxy endpoint, note NSTProxy tunnels HTTPS over http/socks5 protocol — use "http" unless you specifically need SOCKS
3. Check for trailing whitespace or case issues in the value if it comes from config files

Example fix

// before
cfg.set_nstproxy(token=t, channel_id=c, protocol="https")
// after
cfg.set_nstproxy(token=t, channel_id=c, protocol="http")  # or "socks5"

protocol = protocol.strip().lower()
assert protocol in ("http", "socks5"), f"unsupported protocol {protocol!r}"

def is_valid_nstproxy_protocol(p: str) -> bool:
    return isinstance(p, str) and p.strip().lower() in ("http", "socks5")

When it happens

Trigger: Calling set_nstproxy(..., protocol="https"), protocol="socks4", protocol="SOCKS5" (case-sensitive), or passing None.

Common situations: Assuming https proxies work because many proxy vendors support them; uppercase variants; passing a full proxy URL as the protocol argument.

Related errors

• [NSTProxy] token and channel_id are required
• Invalid proxy string format: {proxy_str}
• [NSTProxy] API Error: {data.get('msg', 'Unknown error')}
• [NSTProxy] Invalid API response — expected a non-empty list
• concurrency must be positive

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