GitHub API error querying release tag

Error message

GitHub API error querying release tag {candidate} for {org}/{repo}: HTTP {}

What it means

resolve_github_ref queries the GitHub API for a release with the requested tag. Any non-success, non-404 HTTP status (404 is treated as 'try next candidate') aborts resolution with this error, because the CLI cannot determine whether the pinned version exists.

Solutions

Retry after waiting if the status is 403/429 — likely GitHub API rate limiting; set GITHUB_TOKEN to raise the limit.
Check https://www.githubstatus.com for GitHub API incidents if you see 5xx.
Verify the repo is public or provide credentials for a private repo (403).
Check network/proxy configuration that might intercept api.github.com requests.

Example fix

// before (unauthenticated, rate-limited)
astrid capsule install github:org/repo@1.2.0
// after (authenticated, higher rate limit)
export GITHUB_TOKEN=ghp_...
astrid capsule install github:org/repo@1.2.0

Defensive patterns

Strategy: retry

Try / catch

// retry transient GitHub failures with backoff
for attempt in 0..3 {
    match install_capsule_from_github("org", "repo", Some("1.2.0")).await {
        Ok(_) => break,
        Err(e) if e.to_string().contains("GitHub API error") && attempt < 2 => {
            tokio::time::sleep(std::time::Duration::from_secs(2u64.pow(attempt))).await;
        }
        Err(e) => return Err(e),
    }
}

Prevention

Set GITHUB_TOKEN to avoid unauthenticated rate limits.
Check GitHub API status before bulk installs in CI.
Handle 403/429 with exponential backoff in automation.

When it happens

Trigger: install_from_github or resolve_capsule_to_file calls resolve_github_ref with a version pin; the GET to api.github.com/repos/{org}/{repo}/releases/tags/{candidate} returns a 4xx/5xx status other than NOT_FOUND.

Common situations: GitHub API rate limiting (403/429) from an unauthenticated client; a GitHub outage (5xx); a private repo returning 403 for an unauthenticated request; corporate proxy blocking api.github.com.

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/a6d2b149def21f33. Report an issue: GitHub.

Appendix: source

Thrown at crates/astrid-cli/src/commands/capsule/install_github.rs:68

    org: &str,
    repo: &str,
    version: Option<&str>,
    tag: Option<&str>,
) -> anyhow::Result<String> {
    if let Some(tag) = tag {
        return Ok(tag.to_string());
    }
    if let Some(version) = version {
        for candidate in [format!("v{version}"), version.to_string()] {
            let tag_url = release_tag_url(org, repo, &candidate)?;
            let response = client.get(&tag_url).send().await.with_context(|| {
                format!("failed to query release tag {candidate} for {org}/{repo}")
            })?;
            if response.status() == reqwest::StatusCode::NOT_FOUND {
                continue;
            }
            if !response.status().is_success() {
                bail!(
                    "GitHub API error querying release tag {candidate} for {org}/{repo}: HTTP {}",
                    response.status()
                );
            }
            let json = response
                .json::<serde_json::Value>()
                .await
                .with_context(|| format!("invalid GitHub API response for tag {candidate}"))?;
            return Ok(json
                .get("tag_name")
                .and_then(serde_json::Value::as_str)
                .unwrap_or(&candidate)
                .to_string());
        }
        bail!("no GitHub release found for version {version} in {org}/{repo}");
    }

    tracing::debug!(%org, %repo, "no version/tag pin — resolving latest release");

View on GitHub (pinned to affd8760f4)