charmbracelet/glow · error

can't find README in GitHub repository

Error message

can't find README in GitHub repository

What it means

findGitHubREADME queries the GitHub REST API (https://api.github.com/repos/{owner}/{repo}/readme), parses the JSON for download_url, then GETs that raw URL. This error is the terminal fallback: the API response was not HTTP 200, or the follow-up download of the README blob was not HTTP 200, so no readable source was produced. It aggregates several distinct failures (missing/private repo, rate limiting, deleted README) into one sentinel message.

Source

Thrown at github.go:56

	var result readme
	if err := json.Unmarshal(body, &result); err != nil {
		return nil, fmt.Errorf("unable to parse json: %w", err)
	}

	if res.StatusCode == http.StatusOK {
		//nolint:bodyclose
		// it is closed on the caller
		resp, err := http.Get(result.DownloadURL) //nolint: noctx
		if err != nil {
			return nil, fmt.Errorf("unable to get url: %w", err)
		}

		if resp.StatusCode == http.StatusOK {
			return &source{resp.Body, result.DownloadURL}, nil
		}
	}

	return nil, errors.New("can't find README in GitHub repository")
}

View on GitHub (pinned to e3970c813d)

Solutions

1. Open the same URL in a browser to confirm the repo exists, is public, and shows a README
2. If rate limited, wait or run from a different IP; glow makes unauthenticated API calls, so there is no token flag
3. Bypass the API: pass the raw file URL directly, e.g. glow https://raw.githubusercontent.com/OWNER/REPO/main/README.md
4. Clone the repo locally and run glow on the directory or the README.md file path

Example fix

# before
glow https://github.com/owner/typod-repo

# after (raw file skips the GitHub API entirely)
glow https://raw.githubusercontent.com/owner/repo/main/README.md

func checkGitHubReadable(u *url.URL) error {
	owner, repo, ok := strings.Cut(strings.TrimPrefix(u.Path, "/"), "/")
	if !ok {
		return fmt.Errorf("invalid url: %s", u)
	}
	resp, err := http.Head(fmt.Sprintf("https://api.github.com/repos/%s/%s/readme", owner, repo))
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("github readme endpoint returned %d (repo missing, private, or rate limited)", resp.StatusCode)
	}
	return nil
}

// run before calling glow with the URL:
if err := checkGitHubReadable(u); err != nil {
	log.Fatal(err)
}

src, err := findGitHubREADME(u)
if err != nil {
	if err.Error() == "can't find README in GitHub repository" {
		// fall back to the raw CDN, which is not API-rate-limited
		raw := fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/HEAD/README.md", owner, repo)
		src, err = openRawSource(raw)
	}
	if err != nil {
		return fmt.Errorf("rendering github readme: %w", err)
	}
}

When it happens

Trigger: Running glow with a github.com repo URL where the repo does not exist or is private (API returns 404); exceeding GitHub's unauthenticated rate limit of ~60 requests/hour per IP (API returns 403/429, common on shared CI IPs); the readme download_url request returning any non-200 status; a repo whose default branch README was removed after the API cached a response.

Common situations: Typo in owner or repo segment of the URL; private repository (glow's http.Get sends no credentials or token); CI runners behind NAT that burned the shared rate budget; networks where api.github.com is reachable but raw content redirects are blocked.

Related errors

• can't find README in GitLab repository
• unable to get url: %w
• unable to read http response body: %w
• unable to parse json: %w
• unable to get url: %w

AI-assisted analysis of charmbracelet/glow@e3970c813d (2026-08-15). Data as JSON: /api/errors/3a36c01275d79bc9. Report an issue: GitHub.