README
¶
errorutil Package
The errorutil package provides shared helpers for classifying and inspecting errors returned by the GitHub API and gh CLI.
Overview
This package currently exposes focused helpers for identifying common error categories used across pkg/cli and pkg/parser, including "not found" (404), "forbidden" (403), "gone" (410), rate-limit, and authentication/authorization responses.
Public API
Functions
| Function | Signature | Description |
|---|---|---|
IsNotFoundError |
func(err error) bool |
Returns true when err indicates a "not found" condition by matching case-insensitive 404 or not found text; returns false for nil and non-matching errors |
IsForbiddenError |
func(err error) bool |
Returns true when err indicates an HTTP-style 403/"forbidden" response by matching case-insensitive patterns like HTTP 403 or 403 Forbidden; returns false for nil and non-matching errors |
IsGoneError |
func(err error) bool |
Returns true when err indicates an HTTP-style 410/"gone" response by matching case-insensitive patterns like HTTP 410 or 410 Gone; returns false for nil and non-matching errors |
IsRateLimitError |
func(output string) bool |
Returns true when output indicates GitHub API rate limiting by matching case-insensitive rate limit exceeded (including API rate limit exceeded) or secondary rate limit text |
IsAuthError |
func(output string) bool |
Returns true when output indicates authentication or authorization failures by matching case-insensitive credential-specific markers including GH_TOKEN, GITHUB_TOKEN, authentication, not logged into, unauthorized, permission denied, or SAML enforcement |
IsInsufficientScopesError |
func(err error) bool |
Returns true when err indicates a GitHub GraphQL request was rejected for missing OAuth/PAT scopes by matching the case-insensitive INSUFFICIENT_SCOPES literal; returns false for nil and non-matching errors |
IsAlreadyMergedError |
func(err error) bool |
Returns true when err indicates a gh pr merge operation failed because the pull request was already merged, by matching the case-insensitive phrase already merged or the case-sensitive GraphQL state literal MERGED; returns false for nil, non-matching errors, and failure wording such as could not be merged |
Usage Examples
import "github.com/github/gh-aw/pkg/errorutil"
if errorutil.IsNotFoundError(err) {
// Handle missing resource path
}
if errorutil.IsForbiddenError(err) {
// Handle insufficient permissions
}
if errorutil.IsGoneError(err) {
// Handle expired or deleted resource
}
if errorutil.IsRateLimitError(output) {
// Back off and retry
}
if errorutil.IsAuthError(output) {
// Surface credential guidance
}
if errorutil.IsInsufficientScopesError(err) {
// Prompt for a token with additional scopes
}
if errorutil.IsAlreadyMergedError(err) {
// Treat the merge as already complete
}
Dependencies
Internal:
github.com/github/gh-aw/pkg/logger— package-scoped logging used for error-classification diagnostics.
External:
- None beyond the Go standard library (
strings).
Design Notes
IsNotFoundError,IsForbiddenError, andIsGoneErrorintentionally accept multiple message formats to cover errors produced by GitHub API responses,ghCLI output, andgo-ghwrappers.IsRateLimitErrorandIsAuthErrorprovide shared case-insensitive string classifiers for GitHub API andghCLI output so callers avoid duplicating inline substring checks.IsForbiddenErrorandIsGoneErrorintentionally require HTTP-style status context so unrelated phrases likeforbidden characterorgone awayare not misclassified.IsInsufficientScopesErrorandIsAlreadyMergedErrorcentralize gh CLI error-text classification that would otherwise require inlinestrings.Contains(err.Error(), ...)checks at call sites, keeping the brittle substring matching in one reviewed location. Both are documented exceptions to theerrstringmatchconvention: the gh CLI exposes no structured type, status code, or state for these conditions, so text matching is the only available signal. Because the fragility is centralized here, a gh CLI wording change is fixed in one place and is covered by tests, including negative cases such ascould not be merged.
This specification is automatically maintained by the spec-extractor workflow.
Documentation
¶
Overview ¶
Package errorutil provides shared helpers for classifying and inspecting errors returned by the GitHub API and gh CLI.
Index ¶
- func IsAlreadyMergedError(err error) bool
- func IsAuthError(output string) bool
- func IsForbiddenError(err error) bool
- func IsGoneError(err error) bool
- func IsInsufficientScopesError(err error) bool
- func IsNotFoundError(err error) bool
- func IsNotFoundOutput(output string) bool
- func IsRateLimitError(output string) bool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsAlreadyMergedError ¶ added in v0.87.3
IsAlreadyMergedError reports whether err indicates that a `gh pr merge` operation failed because the pull request was already merged. The gh CLI only surfaces this state via error text: either the phrase "already merged" (matched case-insensitively) or the uppercase GraphQL "MERGED" state literal (matched case-sensitively so that ordinary wording such as "could not be merged" or "not merged" is not misclassified as success). It returns false when err is nil.
Exception: `gh pr merge` exposes no structured state for this condition, so classification is necessarily a substring match. The match lives here rather than at call sites so the fragile literals are documented, tested, and updated in one place.
func IsAuthError ¶ added in v0.87.1
IsAuthError reports whether output indicates an authentication or authorization issue from the GitHub API or gh CLI.
func IsForbiddenError ¶ added in v0.74.5
IsForbiddenError reports whether err represents an HTTP 403 / "forbidden" response. It returns false when err is nil. The check is case-insensitive and only matches HTTP-style 403 patterns such as "HTTP 403" or "403 Forbidden", which avoids misclassifying unrelated errors like "forbidden character".
func IsGoneError ¶ added in v0.74.5
IsGoneError reports whether err represents an HTTP 410 / "gone" response. It returns false when err is nil. The check is case-insensitive and only matches HTTP-style 410 patterns such as "HTTP 410" or "410 Gone", which avoids misclassifying unrelated errors like "connection has gone away".
func IsInsufficientScopesError ¶ added in v0.87.3
IsInsufficientScopesError reports whether err indicates that a GitHub GraphQL API request was rejected because the authenticated token is missing required OAuth/PAT scopes. The gh CLI and GitHub GraphQL API surface this as the literal "INSUFFICIENT_SCOPES" error type. It returns false when err is nil.
Exception: the gh CLI returns this condition only as error text, with no machine-readable type or status code, so classification is necessarily a substring match. The match lives here rather than at call sites so the fragile literal is documented, tested, and updated in one place.
func IsNotFoundError ¶
IsNotFoundError reports whether err represents an HTTP 404 / "not found" response. It returns false when err is nil. The check is case-insensitive and matches both the numeric literal "404" and the phrase "not found", which covers all known forms returned by the GitHub API, the gh CLI, and the go-gh library.
func IsNotFoundOutput ¶ added in v0.86.3
IsNotFoundOutput reports whether output represents an HTTP 404 / "not found" response. The check is case-insensitive and matches both the numeric literal "404" and the phrase "not found".
func IsRateLimitError ¶ added in v0.87.1
IsRateLimitError reports whether output indicates a GitHub API rate-limit error. The check is case-insensitive and matches known API phrases.
Types ¶
This section is empty.
Source Files