hiyouga/LlamaFactory · error · HTTPException

Invalid URL: {e}

Error message

Invalid URL: {e}

What it means

Raised as HTTP 400 by check_ssrf_url's final except: any non-gaierror exception during URL parsing, getaddrinfo, ipaddress parsing, or the is_global check is reported as 'Invalid URL: <exception>'. Common underlying causes: an invalid port (e.g. 'http://host:99999/'), an IP literal ipaddress cannot parse, or other OS-level resolution errors.

Source

Thrown at src/llamafactory/api/common.py:96

        if not hostname:
            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid URL hostname.")

        ip_info = socket.getaddrinfo(hostname, parsed_url.port)
        ip_address_str = ip_info[0][4][0]
        ip = ipaddress.ip_address(ip_address_str)

        if not ip.is_global:
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Access to private or reserved IP addresses is not allowed.",
            )

    except socket.gaierror:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST, detail=f"Could not resolve hostname: {parsed_url.hostname}"
        )
    except Exception as e:
        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Invalid URL: {e}")

View on GitHub (pinned to f28afaf635)

Solutions

1. Read the embedded exception text — it names the real problem (port range, address family, etc.).
2. Validate the URL client-side with new URL() / urllib.parse and a port range check (1-65535).
3. For IPv6 literals use bracketed form: http://[2001:db8::1]:8080/img.png.
4. Simplify the URL (drop port, use https default) to isolate the failing component.

Example fix

// before
url: 'http://example.com:99999/img.png'
// after
url: 'http://example.com:8080/img.png'

from urllib.parse import urlparse
def url_wellformed(u):
    p = urlparse(u)
    if p.scheme not in ("http", "https") or not p.hostname:
        return False
    if p.port is not None and not (1 <= p.port <= 65535):
        return False
    return True

const wellFormedUrl = (u) => { try { const p = new URL(u); return ['http:','https:'].includes(p.protocol) && !!p.hostname && (!p.port || (+p.port <= 65535)); } catch { return false; } };

catch (e) { if (e.status === 400 && e.detail?.startsWith('Invalid URL:')) { log(e.detail); /* underlying exception names the real issue */ } throw e; }

When it happens

Trigger: URL with out-of-range or non-numeric port (http://example.com:70000/img.png) causing getaddrinfo ValueError; IPv6 literals with bad bracket syntax; other malformed URL edge cases that pass urlparse but break later steps.

Common situations: Config-driven port numbers concatenated without validation; IPv6 URLs copied without brackets; exotic proxy-generated URLs.

Related errors

• Only HTTP/HTTPS URLs are allowed.
• Invalid URL hostname.
• Could not resolve hostname: {parsed_url.hostname}
• Invalid or inaccessible file path.
• Access to private or reserved IP addresses is not allowed.

AI-assisted analysis of hiyouga/LlamaFactory@f28afaf635 (2026-08-14). Data as JSON: /api/errors/973ccd5182147c7d. Report an issue: GitHub.