vllm-project/vllm · error · ValueError

Invalid HTTP URL: A valid HTTP URL must have scheme 'http' o

Error message

Invalid HTTP URL: A valid HTTP URL must have scheme 'http' or 'https'.

What it means

Raised by HTTPConnection._validate_http_url (vllm/connections.py) when a URL passed to the client parses with a scheme other than http or https. vLLM validates URLs before issuing requests (model downloads, API calls) so misconfigured endpoints fail fast instead of producing confusing downstream errors.

Source

Thrown at vllm/connections.py:229

    def get_sync_client(self) -> requests.Session:
        if self._sync_client is None or not self.reuse_client:
            self._sync_client = requests.Session()

        return self._sync_client

    # NOTE: We intentionally use an async function even though it is not
    # required, so that the client is only accessible inside async event loop
    async def get_async_client(self) -> aiohttp.ClientSession:
        if self._async_client is None or not self.reuse_client:
            self._async_client = aiohttp.ClientSession(trust_env=True)

        return self._async_client

    def _validate_http_url(self, url: str):
        parsed_url = parse_url(url)

        if parsed_url.scheme not in ("http", "https"):
            raise ValueError(
                "Invalid HTTP URL: A valid HTTP URL must have scheme 'http' or 'https'."
            )

    def _headers(self, **extras: str) -> MutableMapping[str, str]:
        return {"User-Agent": f"vLLM/{VLLM_VERSION}", **extras}

    def get_response(
        self,
        url: str,
        *,
        stream: bool = False,
        timeout: float | None = None,
        extra_headers: Mapping[str, str] | None = None,
        allow_redirects: bool = True,
    ):
        self._validate_http_url(url)

        client = self.get_sync_client()

View on GitHub (pinned to c794754062)

Solutions

Add or correct the scheme so the URL starts with http:// or https://.
If the resource lives on HuggingFace or S3, use the HTTP endpoint URL (or the dedicated HF download path) rather than the native scheme.
Check for stray whitespace or a leading path fragment before the scheme in the URL string.

Example fix

# before
client.get_response("hf.co/Nemotron/weights.bin")
# after
client.get_response("https://hf.co/Nemotron/weights.bin")

Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse

def is_http_url(url: str) -> bool:
    return urlparse(url).scheme in ("http", "https")

assert is_http_url(os.environ["VLLM_DOWNLOAD_URL"])

Type guard

def is_http_url(url: str) -> bool:
    return urlparse(url).scheme in ("http", "https")

Try / catch

try:
    resp = await client.get_response(url)
except ValueError as e:
    if "scheme" in str(e):
        url = "https://" + url.lstrip("/")  # repair only if clearly a bare host
    raise

Prevention

Validate endpoint URLs at config load time with urlparse, not at request time.
Centralize URL construction in one helper that always injects the scheme.

When it happens

Trigger: Passing a URL with a scheme like ftp://, file://, s3://, hf://, or a bare host without a scheme to any HTTPConnection method that calls _validate_http_url (e.g. get_response on the shared async client).

Common situations: Setting an environment variable or CLI flag for a model/metrics/API endpoint to a non-HTTP URI; forgetting the https:// prefix on a host; pointing a download URL at an object-store or HF URI instead of its HTTP endpoint.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/1b9f3fbf81690152. Report an issue: GitHub.