What causes "{}: API metadata has no tap_git_head" in jdx/mise?

Clear mise's Homebrew API cache and retry

{}: API metadata has no tap_git_head

Error message

{}: API metadata has no tap_git_head

What it means

mise fetches the formula .rb pinned to the API snapshot's git commit so the formula is verifiable and consistent with the source metadata. Without tap_git_head in the API JSON the commit is unknown, the pinning/verification chain breaks, and check_buildable rejects the source build up front.

Source

Thrown at src/system/packages/brew/source.rs:83

    };
    if let Some(using) = &src.using {
        bail!(
            "{}: source uses the {using:?} download strategy, which mise cannot build from \
             (and no bottle exists for this machine)",
            formula.name,
        );
    }
    if src.checksum.is_none() {
        bail!("{}: source archive has no sha256 in the API", formula.name);
    }
    // the formula .rb must be pinned to the API snapshot's commit and
    // verifiable — evaluating a newer/unverified formula against older
    // source metadata would build the wrong thing
    if formula.ruby_source_path.is_none() {
        bail!("{}: API metadata has no ruby_source_path", formula.name);
    }
    if formula.tap_git_head.is_none() {
        bail!("{}: API metadata has no tap_git_head", formula.name);
    }
    if formula
        .ruby_source_checksum
        .as_ref()
        .and_then(|c| c.sha256.as_deref())
        .is_none()
    {
        bail!("{}: API metadata has no formula checksum", formula.name);
    }
    Ok(())
}

/// Build a formula from source into its keg and link it.
pub async fn build(
    rf: &ResolvedFormula,
    closure: &[ResolvedFormula],
    pr: &dyn SingleReport,
) -> Result<()> {

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Clear mise's Homebrew API cache and retry
Update mise to the latest version in case metadata handling changed
Install the formula with native Homebrew or wait for consistent upstream metadata

Defensive patterns

Strategy: retry

Try / catch

match check_buildable(&formula) {
    Err(e) if e.to_string().contains("tap_git_head") => {
        clear_homebrew_api_cache()?;
        check_buildable(&formula)
    }
    other => other,
}

Prevention

Refresh the API cache after tap updates to get consistent snapshots with tap_git_head
Update mise regularly so pinning metadata is parsed correctly
Use native brew when metadata stays inconsistent

When it happens

Trigger: formula.tap_git_head is None during check_buildable on a source-build path (host had no bottle).

Common situations: Stale or truncated Homebrew API cache entries; tap metadata that omits the git head; races between tap updates and API generation.

Related errors

AI-assisted analysis of jdx/mise@9dcfcaa0dc (2026-08-17). Data as JSON: /api/errors/f1d7b270e96649b5. Report an issue: GitHub.