What causes "github api returned status %d" in gastownhall/beads?

Wait for the GitHub API rate limit to reset (check the X-RateLimit-Reset header) or set a GITHUB_TOKEN if supported

github api returned status %d

Error message

github api returned status %d

What it means

fetchLatestGitHubRelease queries the GitHub API for the latest release. If the HTTP response status is anything other than 200 OK, it aborts and returns this error with the numeric status code. The library deliberately avoids parsing the body when the API did not return a success response, so callers get a clear signal that the request itself failed.

Source

Thrown at cmd/bd/doctor/version.go:234

		Timeout: 5 * time.Second,
	}

	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return "", err
	}

	// Set User-Agent as required by GitHub API
	req.Header.Set("User-Agent", "beads-cli-doctor")

	resp, err := client.Do(req)
	if err != nil {
		return "", err
	}
	defer func() { _ = resp.Body.Close() }()

	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("github api returned status %d", resp.StatusCode)
	}

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}

	var release struct {
		TagName string `json:"tag_name"`
	}

	if err := json.Unmarshal(body, &release); err != nil {
		return "", err
	}

	// Strip 'v' prefix if present
	version := strings.TrimPrefix(release.TagName, "v")

View on GitHub (pinned to 71377f2769)

Solutions

Wait for the GitHub API rate limit to reset (check the X-RateLimit-Reset header) or set a GITHUB_TOKEN if supported
Check network/proxy configuration; verify `curl -i https://api.github.com/repos/gastownhall/beads/releases/latest` returns 200
Retry later if the API is returning 5xx; check https://www.githubstatus.com
Run `bd doctor` again once connectivity is restored

Defensive patterns

Strategy: retry

Validate before calling

resp, _ := http.Get(apiURL)
if resp != nil {
  defer resp.Body.Close()
  if resp.StatusCode == http.StatusForbidden && resp.Header.Get("X-RateLimit-Remaining") == "0" {
    // rate-limited: wait for X-RateLimit-Reset before retrying
  }
}

Try / catch

latest, err := fetchLatestGitHubRelease(ctx)
if err != nil {
  var statusErr interface{ Unwrap() error }
  log.Printf("version check skipped: %v", err) // non-fatal for doctor
}

Prevention

Avoid running version checks in tight loops to stay under the 60/hr unauthenticated GitHub limit
Use an authenticated token for GitHub API calls when available
Handle all non-200 codes explicitly rather than assuming 404/403 never happen
Check githubstatus.com before assuming a local problem on 5xx

When it happens

Trigger: Calling fetchLatestGitHubRelease (via `bd doctor` version check) when the GitHub API responds with a non-200 status: 403 rate-limit, 404 if the repo moved, 5xx server errors, or network-proxied error pages.

Common situations: Hitting GitHub's unauthenticated 60-req/hour rate limit (403 with X-RateLimit-Remaining: 0), running `bd doctor` behind a corporate proxy that returns 407/502, or the repository being renamed/made private (404).

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/ea696c7b9563aeb7. Report an issue: GitHub.