unslothai/unsloth · error · ValueError

Provider base URL contains invalid characters.

Error message

Provider base URL contains invalid characters.

What it means

Raised when the stripped base URL contains whitespace anywhere, control characters (codepoint < 32 or 127), or a backslash. These characters cannot appear in a legitimate endpoint URL and are classic injection/smuggling vectors for parser-differential attacks, so validation fails before urlsplit ever runs.

Source

Thrown at studio/backend/core/inference/providers.py:874

    The backend issues outbound requests to this URL with the caller's decrypted
    API key attached, so it is caller-controlled server-side egress. Only shapes
    that can never be a real provider endpoint are refused: a non-http(s) scheme,
    control characters, a missing host, and cloud metadata services. Plain http,
    loopback, LAN hosts, odd ports, query strings and basic-auth userinfo all
    stay valid -- Ollama, llama.cpp, vLLM and custom gateways rely on them. A
    caller-supplied hostname is resolved far enough to apply the metadata block
    to DNS aliases of it; rejecting other private addresses stays opt-in.

    Normalization is strip + trailing-slash removal only (what the client did
    before), so validating an already-validated URL returns it unchanged.
    """
    if not isinstance(base_url, str) or not base_url.strip():
        raise ValueError("Provider base URL is required.")

    raw = base_url.strip()
    if any(char.isspace() or ord(char) < 32 or ord(char) == 127 for char in raw) or "\\" in raw:
        raise ValueError("Provider base URL contains invalid characters.")

    try:
        parts = urlsplit(raw)
        port = parts.port
        hostname = parts.hostname
    except ValueError as exc:
        raise ValueError("Provider base URL is malformed.") from exc

    scheme = parts.scheme.lower()
    if scheme not in ("http", "https"):
        raise ValueError("Provider base URL must use http or https.")
    # Userinfo stays allowed for gateways behind basic auth; the checks below read
    # the parsed hostname, so http://api.openai.com@169.254.169.254/ is caught.
    if not hostname:
        raise ValueError("Provider base URL must contain a hostname.")

    hostname = hostname.rstrip(".")
    if _metadata_host(hostname) or _resolves_to_metadata(hostname, port, scheme):

View on GitHub (pinned to 203007d190)

Solutions

1. Retype or carefully re-paste the URL, removing embedded spaces/line breaks.
2. Sanitize input at the form level: reject or strip control characters before submit.
3. Inspect the raw string with repr() to find the offending character.

Example fix

# before
validate_provider_base_url("https://api.example.com/v1\n")
# after
validate_provider_base_url("https://api.example.com/v1")

def has_no_bad_chars(url: str) -> bool:
    return not any(c.isspace() or ord(c) < 32 or ord(c) == 127 for c in url) and "\\" not in url

When it happens

Trigger: A pasted URL containing a newline, tab, or trailing invisible character; a backslash-based path like http://host\path; a URL copied from a PDF with soft line breaks embedded.

Common situations: Copy-paste from documents/slides introducing hidden characters; user typing a URL with an embedded space; crafted input attempting header or path confusion.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Provider base URL is required.
• Provider base URL hostname could not be resolved.
• Provider base URL points at a private address, which is disa
• Provider base URL is malformed.
• Provider base URL must use http or https.

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/9e3528b03f8b30bf. Report an issue: GitHub.