invoke-ai/InvokeAI · error · UnsafeDownloadURLException

Download URL '{url}' has an invalid port.

Error message

Download URL '{url}' has an invalid port.

What it means

urlsplit().port raises ValueError when the URL's port is non-numeric or out of the allowed range. validate_download_url catches this and re-raises it as UnsafeDownloadURLException, rejecting the URL before any connection is attempted.

Source

Thrown at invokeai/app/util/ssrf.py:209

    loopback record is rejected, because we cannot control which one the HTTP client picks.

    An unresolvable host is allowed through to the HTTP client, so that offline test
    environments and mocked sessions keep working. That is only safe because the session
    from `build_guarded_session()` re-checks the address it actually connects to.
    """
    parts = urlsplit(str(url))

    if parts.scheme.lower() not in ALLOWED_SCHEMES:
        raise UnsafeDownloadURLException(f"Unsupported URL scheme '{parts.scheme}'. Only http and https are allowed.")

    host = parts.hostname
    if not host:
        raise UnsafeDownloadURLException(f"Download URL '{url}' has no host.")

    try:
        port = parts.port
    except ValueError as e:
        raise UnsafeDownloadURLException(f"Download URL '{url}' has an invalid port.") from e

    if allow_private_urls:
        return

    for spelling in _host_spellings(host):
        literal = _parse_ipv4_literal(spelling)
        if literal is not None:
            candidates = [literal]
        else:
            try:
                candidates = _resolve(spelling, port)
            except (OSError, UnicodeError, ValueError):
                continue
        for candidate in candidates:
            check_address(candidate, host)


def _check_socket(sock: socket.socket) -> None:

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Fix the port in the URL to a valid number 1-65535
2. Remove the port entirely to use the scheme default (80/443)
3. Validate the URL with urllib before submitting it
4. If ports vary per environment, build the URL programmatically with int(port) validated in range

Example fix

// before
url = 'https://example.com:99999/model.safetensors'  # invalid port
// after
url = 'https://example.com:8443/model.safetensors'

from urllib.parse import urlsplit

def validate_port(url):
    try:
        port = urlsplit(str(url)).port
    except ValueError:
        raise ValueError(f"URL has invalid port: {url}")
    if port is not None and not (1 <= port <= 65535):
        raise ValueError(f"port out of range: {port}")

from invokeai.app.util.ssrf import UnsafeDownloadURLException
try:
    download(url)
except UnsafeDownloadURLException as e:
    if 'invalid port' in str(e):
        raise ValueError(f"Correct the port in: {url}") from e
    raise

When it happens

Trigger: URLs like 'https://example.com:99999/file' (port > 65535) or 'https://example.com:abc/file' (non-numeric port) passed to the download API.

Common situations: Hand-edited URLs with typo'd ports; copy-paste artifacts like double colons (host::port); generated URLs where a port variable was empty or contained a non-digit character.

Related errors

• Download URL '{url}' has no host.
• Cannot derive a safe filename for {url} from '{file_name}'
• Unsupported URL scheme '{parts.scheme}'. Only http and https
• only relative download paths accepted
• Invalid image name, potential directory traversal detected

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/e3788583fea2cf14. Report an issue: GitHub.