GitHub API returned {} fetching release {resolved_ref} of {o

Error message

GitHub API returned {} fetching release {resolved_ref} of {org}/{repo}

What it means

`resolve_capsule_to_file` calls the GitHub releases API to look up release metadata. If the HTTP response status is not a success, it bails embedding the numeric/text status and the ref/org/repo being resolved. This is a guarded HTTP failure — the API answered, but with an error status — surfaced with context instead of letting the request proceed to JSON parsing.

Source

Thrown at crates/astrid-cli/src/commands/capsule/install.rs:443

    // Authenticated when a token is present (see `github_api_client`).
    let client = github_api_client()?;

    let resolved_ref = resolve_github_ref(&client, &org, &repo, version, tag).await?;

    // Fetch the resolved release's assets and pick the right `<name>.capsule`
    // (the same selection the install path uses), so a release shipping
    // several capsules downloads the one the seal asked for rather than the
    // first. A missing `.capsule` asset is a hard error — seal requires
    // pre-built release artifacts.
    let api_url = release_tag_url(&org, &repo, &resolved_ref)?;
    let response = client
        .get(&api_url)
        .send()
        .await
        .context("failed to fetch release metadata")?;
    if !response.status().is_success() {
        bail!(
            "GitHub API returned {} fetching release {resolved_ref} of {org}/{repo}",
            response.status()
        );
    }
    let json: serde_json::Value = response.json().await.context("invalid release metadata")?;
    let assets = json
        .get("assets")
        .and_then(serde_json::Value::as_array)
        .map(Vec::as_slice)
        .unwrap_or_default();
    let candidates = capsule_assets(assets);
    let names: Vec<&str> = candidates.iter().map(|(n, _)| n.as_str()).collect();
    let Some(idx) = pick_capsule(&names, name_hint)? else {
        bail!(
            "release {resolved_ref} of {org}/{repo} ships no .capsule asset — \
             seal requires pre-built release artifacts"
        );
    };

View on GitHub (pinned to affd8760f4)

Solutions

Check the status in the message: 404 means the ref/repo doesn't exist — verify the tag and org/repo spelling.
If 403/429, wait for the GitHub rate-limit window or authenticate with a GITHUB_TOKEN.
For private repos, ensure credentials are configured so API calls are authorized.
Retry later on 5xx (check https://www.githubstatus.com), or use a cached/cloned source install meanwhile.

Defensive patterns

Strategy: retry

Validate before calling

// verify the tag exists and you are within the rate limit before resolving
// curl -s -o /dev/null -w '%{http_code}' https://api.github.com/repos/ORG/REPO/releases/tags/TAG  # expect 200
// curl -s https://api.github.com/rate_limit | jq .resources.core.remaining

Try / catch

match resolve_capsule_to_file(pin).await {
    Err(e) if e.to_string().contains("GitHub API returned 403") =>
        eprintln!("GitHub rate limit hit; set GITHUB_TOKEN or wait for the window to reset."),
    Err(e) if e.to_string().contains("GitHub API returned 404") =>
        eprintln!("Release/tag or repo not found; verify the pinned ref."),
    other => other.expect("resolve failed"),
}

Prevention

Authenticate GitHub API calls (GITHUB_TOKEN) to raise the 60 req/hr anonymous limit.
Verify the pinned tag and org/repo spelling before installing.
Cache release lookups in CI to reduce API calls.
Retry with backoff on 5xx and monitor githubstatus.com for incidents.

When it happens

Trigger: The `client.get(&api_url)` response has `!response.status().is_success()` — 404 for a nonexistent tag/release or repo, 403 for GitHub API rate limiting, 401 for private repos without a token, 5xx from GitHub.

Common situations: Exhausted unauthenticated GitHub API rate limit (60 req/hr) returning 403; typo in the pinned tag yielding 404; private repository without GITHUB_TOKEN; GitHub incidents returning 5xx.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/e01e4429596f1123. Report an issue: GitHub.