unslothai/unsloth · error · ValueError

Provider base URL hostname could not be resolved.

Error message

Provider base URL hostname could not be resolved.

What it means

Raised in _reject_non_public (active only when UNSLOTH_STUDIO_BLOCK_PRIVATE_PROVIDER_URLS=1) when socket.getaddrinfo for the provider base URL's hostname fails with OSError or UnicodeError. The resolver produced no answer, so the server cannot prove the host is public and fails closed. The surrounding comment notes an earlier fast check was removed, so a slow resolver is tolerated — only a hard resolution failure lands here.

Source

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

        # this reads that rather than starting a second bounded lookup: on a
        # slow resolver the pair of them would each spend a deadline before the
        # fallback below spent a third.
        resolved = _cached_addresses(hostname)
        if resolved is None:
            # This path blocked on an unbounded getaddrinfo before the metadata
            # check existed, and a resolver slower than that check's deadline is
            # ordinary (the Linux default is 5s per server, twice). Falling back
            # to the same unbounded call keeps a slow-but-working resolver from
            # turning into a refusal here, where "no answer" fails closed.
            import socket
            try:
                infos = socket.getaddrinfo(
                    _transport_host(hostname),
                    port or (443 if scheme == "https" else 80),
                    type = socket.SOCK_STREAM,
                )
            except (OSError, UnicodeError) as exc:
                raise ValueError("Provider base URL hostname could not be resolved.") from exc
            resolved = tuple(str(info[4][0]) for info in infos)
        addresses = [ipaddress.ip_address(address.split("%", 1)[0]) for address in resolved]
    if not addresses or any(not ip.is_global for ip in addresses):
        raise ValueError(
            "Provider base URL points at a private address, which is disabled on this "
            f"server ({_BLOCK_PRIVATE_ENV}=1)."
        )


def validate_provider_base_url(base_url: str) -> str:
    """Return a normalized provider base URL, or raise ``ValueError``.

    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

View on GitHub (pinned to 203007d190)

Solutions

1. Verify the hostname resolves from the server: dig/nslookup <host>.
2. Fix typos in the provider base URL configuration.
3. If the host is genuinely internal, note the private-URL block is opt-in — unset UNSLOTH_STUDIO_BLOCK_PRIVATE_PROVIDER_URLS only if the deployment allows private endpoints.
4. Repair container/host DNS (resolv.conf, dnsmasq) if resolution is broken server-wide.

Example fix

# before
validate_provider_base_url("https://api.openai.com.exmaple/v1")
# after
validate_provider_base_url("https://api.openai.com/v1")

import socket
socket.getaddrinfo(hostname, 443, type=socket.SOCK_STREAM)  # raises before the API if DNS is broken

def hostname_resolves(host: str) -> bool:
    import socket
    try:
        socket.getaddrinfo(host, 443, type=socket.SOCK_STREAM)
        return True
    except (OSError, UnicodeError):
        return False

try:
    validate_provider_base_url(url)
except ValueError as e:
    if "could not be resolved" in str(e):
        flag_bad_hostname(url)

When it happens

Trigger: Configuring a custom provider base URL whose hostname has no DNS record (typo, stale internal name) while the private-URL block is enabled; a hostname with invalid unicode; resolver outage on the host.

Common situations: Typos like 'api.openai.com.example', internal DNS names that the server's resolver does not know, containers with broken resolv.conf, or a provider domain that was decommissioned.

Related errors

• Provider base URL points at a private address, which is disa
• Provider base URL is required.
• Provider base URL contains invalid characters.
• 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/4ba5678a8f2462ce. Report an issue: GitHub.