invoke-ai/InvokeAI · error · UnsafeDownloadURLException

Unsupported URL scheme '{parts.scheme}'. Only http and https

Error message

Unsupported URL scheme '{parts.scheme}'. Only http and https are allowed.

What it means

validate_download_url only permits http and https (ALLOWED_SCHEMES). Any other URL scheme (ftp, file, data, etc.) is rejected up-front with UnsafeDownloadURLException before any DNS or connection work.

Source

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

            "Set `allow_private_download_urls` in invokeai.yaml to permit downloads from loopback "
            "and private-network addresses."
        )


def validate_download_url(url: str, allow_private_urls: bool = False) -> None:
    """Reject `url` up front if it obviously points somewhere only the server can reach.

    Every address the host resolves to must be public — a hostname with both a public and a
    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:

View on GitHub (pinned to 0b6a024f2f)

Solutions

1. Use an http:// or https:// URL for the download
2. Download from non-http sources manually and place the file in the models directory
3. Add the scheme (e.g. https://) if it was omitted from the URL
4. Check the URL for typos or hidden characters corrupting the scheme

Example fix

// before
url = 'ftp://example.com/model.safetensors'
// after
url = 'https://example.com/model.safetensors'

from urllib.parse import urlsplit

def validate_scheme(url):
    scheme = urlsplit(str(url)).scheme.lower()
    if scheme not in ('http', 'https'):
        raise ValueError(f"scheme must be http/https, got '{scheme}'")

from invokeai.app.util.ssrf import UnsafeDownloadURLException
try:
    download(url)
except UnsafeDownloadURLException as e:
    if 'Unsupported URL scheme' in str(e):
        url = 'https://' + str(url).split('://', 1)[-1]
        download(url)
    else:
        raise

When it happens

Trigger: Passing a download URL like ftp://host/model.safetensors, file:///path, or data: URI to the download API; a URL with no scheme (urlsplit leaves scheme empty, which is not in ALLOWED_SCHEMES).

Common situations: Copy-pasting an FTP link from a model index; attempting local file:// downloads through the remote-download path; missing 'http://' prefix so scheme parses as empty.

Related errors

• Download URL '{url}' has no host.
• Download URL '{url}' has an invalid port.
• Cannot derive a safe filename for {url} from '{file_name}'
• Invalid image name, potential directory traversal detected
• Parent directory references not allowed in subfolder path

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