brew-cask: unsupported tap URL for '{name}'; only GitHub tap

Error message

brew-cask: unsupported tap URL for '{name}'; only GitHub tap URLs can be fetched directly

What it means

When a cask is requested from a tap, the fetcher builds a raw JSON API URL from the tap's owner/name. Only GitHub-hosted taps (github.com/owner/tap) can be fetched directly; `tap_raw_base` returns None for any other tap URL scheme, producing this error. The tool will not guess raw-file URLs for non-GitLab/GitHub forges.

Source

Thrown at src/system/packages/brew/cask/fetch.rs:34

            .and_then(super::super::api::github_raw_base)
    {
        let url = format!("{raw_base}/api/cask/{name}.json");
        match fetch_cask_url(name, &url, Some(normalize_cask_raw_base(raw_base)), false).await {
            Ok(cask) => return Ok(cask),
            Err(err) => debug!(
                "brew-cask: {name} unavailable in parent tap metadata ({err}); falling back to official metadata"
            ),
        }
    }
    let (url, raw_base) = match tap_name {
        Some(("homebrew", "cask", token)) => (
            format!("{API_BASE}/cask/{token}.json"),
            Some(HOMEBREW_CASK_RAW.to_string()),
        ),
        Some((owner, tap, token)) => {
            let Some(base) = super::super::api::tap_raw_base(owner, tap, req.tap_url.as_deref())
            else {
                bail!(
                    "brew-cask: unsupported tap URL for '{name}'; only GitHub tap URLs can be fetched directly"
                );
            };
            (
                format!("{base}/api/cask/{token}.json"),
                Some(normalize_cask_raw_base(base)),
            )
        }
        None => (
            format!("{API_BASE}/cask/{name}.json"),
            Some(HOMEBREW_CASK_RAW.to_string()),
        ),
    };
    match fetch_cask_url(requested_token, &url, raw_base.clone(), official_api).await {
        Ok(cask) => Ok(cask),
        Err(api_err) => {
            let (owner, tap) = match tap_name {
                Some((owner, tap, _)) if owner != "homebrew" || tap != "cask" => (owner, tap),

View on GitHub (pinned to afd2eddd3a)

Solutions

Host or mirror the tap on GitHub so its URL is github.com/<owner>/<tap>.
If a GitLab tap, verify the tap URL is in the recognized GitLab form supported by tap_raw_base; otherwise it's unsupported.
Bypass direct fetching: install the tap with real `brew tap` first so the cask can be read locally instead of via the raw API.
Rewrite MISE_BREW_TAP_URL (or equivalent setting) to a GitHub URL for the same tap.

Example fix

// before
brew = { tap_url = "https://git.example.com/team/homebrew-tap" }
// after
brew = { tap_url = "https://github.com/team/homebrew-tap" }

Defensive patterns

Strategy: fallback

Validate before calling

function isGithubTap(url) {
  try {
    const u = new URL(url);
    return u.hostname === "github.com" && /^\/[^/]+\/[^/]+/.test(u.pathname);
  } catch { return false; }
}
// check before configuring tap_url

Type guard

function isGithubTapUrl(u: string | undefined): u is string {
  return !!u && new URL(u).hostname === "github.com";
}

Try / catch

try {
  installCask(name);
} catch (e) {
  if (String(e).includes("unsupported tap URL")) {
    // fallback: shell out to `brew tap` + local install instead of direct fetch
    execSync(`brew tap ${owner}/${tap}`);
  } else throw e;
}

Prevention

Host taps on GitHub for direct fetching
Use recognized gitlab.com URL forms if on GitLab
Pre-install non-GitHub taps with `brew tap` so local lookup works
Test tap URLs with a plain HTTPS fetch before configuring them

When it happens

Trigger: Installing or resolving a cask whose tap_url points at a non-GitHub tap (e.g. a GitLab-hosted tap, a plain HTTP tap URL, or a locally-registered forge), where tap_raw_base cannot derive a raw base.

Common situations: Users pointing mise's brew backend at self-hosted or alternative-forge taps, internal company taps on private Git servers, and taps migrated off GitHub.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/94cbd1064da11190. Report an issue: GitHub.