What causes "unsupported bundle URL scheme; use https" in Hmbown/CodeWhale?

Use an https:// URL for the bundle (e.g. https://example.com/bundle.toml).

unsupported bundle URL scheme; use https

Error message

unsupported bundle URL scheme; use https

What it means

validate_bundle_url rejects bundle URLs whose scheme is not http or https. The library only supports fetching config bundles over web schemes; schemes like file://, ftp://, or data:// are refused before any request is made, since the bundle fetcher is a network client (reqwest) and other schemes are not part of its threat model. The message points the user at https as the intended scheme.

Solutions

Use an https:// URL for the bundle (e.g. https://example.com/bundle.toml).
If the bundle is a local file, distribute it via a local HTTP server (http://127.0.0.1:PORT is allowed for loopback) instead of file://.
Fix the URL typo so the scheme parses as http or https.
Host the bundle on an internal HTTPS mirror reachable from your network.

Example fix

// before
codewhale bundle add file:///srv/team-config.toml
// after
codewhale bundle add https://config.internal.example/team-config.toml

Defensive patterns

Strategy: validation

Validate before calling

let url = reqwest::Url::parse(input)?;
if !matches!(url.scheme(), "http" | "https") {
    return Err(anyhow!("bundle URL must use http(s), got: {}", url.scheme()));
}

Type guard

fn is_web_url(u: &reqwest::Url) -> bool {
    matches!(u.scheme(), "http" | "https")
}

Prevention

Always prefix bundle locations with https:// in scripts and docs.
Never pass local file paths where a URL is expected; serve locally over loopback http instead.
Validate URLs with a parser (reqwest::Url::parse) before storing them in config.

When it happens

Trigger: Passing a URL with a non-web scheme to bundle fetch/validate paths — e.g. `codewhale bundle add file:///etc/config.toml`, an ftp:// URL, or a URL missing a scheme so it fails to parse into a web URL — from fetch_bundle or validate_bundle_redirect.

Common situations: Pasting a local file path instead of a hosted bundle URL; copying an internal mirror link that uses ftp or a custom proxy scheme; typos like `htp://` that leave the URL schemeless after parsing; scripts interpolating schemeless hostnames.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/04a3ab732b04a653. Report an issue: GitHub.

Appendix: source

Thrown at crates/cli/src/config_bundles.rs:816

        );
    }

    // Read at most MAX_BUNDLE_BYTES + 1 so an oversize body is detected
    // rather than silently truncated.
    let mut buffer = Vec::new();
    let body = response;
    body.take(MAX_BUNDLE_BYTES + 1)
        .read_to_end(&mut buffer)
        .map_err(|_| anyhow!("reading remote bundle failed"))?;
    if buffer.len() as u64 > MAX_BUNDLE_BYTES {
        bail!("remote bundle exceeds the {MAX_BUNDLE_BYTES} byte limit; refused");
    }
    Ok(buffer)
}

fn validate_bundle_url(url: &reqwest::Url) -> Result<()> {
    if !matches!(url.scheme(), "http" | "https") {
        bail!("unsupported bundle URL scheme; use https");
    }
    if !url.username().is_empty() || url.password().is_some() {
        bail!("bundle URLs may not include credentials");
    }
    let host = url.host_str().context("bundle URL must include a host")?;
    match url.scheme() {
        "https" => Ok(()),
        "http" if is_loopback_bundle_host(host) => Ok(()),
        "http" => bail!("plain http is only allowed for loopback hosts; use https"),
        _ => unreachable!("scheme was validated above"),
    }
}

fn validate_bundle_redirect(initial_scheme: &str, next_url: &reqwest::Url) -> Result<()> {
    validate_bundle_url(next_url)?;
    if next_url.scheme() != initial_scheme {
        bail!("bundle redirects may not change URL scheme");
    }

View on GitHub (pinned to 73e0f67d83)