666ghj/MiroFish · error · StarHistoryError

GitHub GraphQL request failed (exit {completed.returncode})

Error message

GitHub GraphQL request failed (exit {completed.returncode})

What it means

Raised when the `gh api graphql` subprocess completes with a non-zero exit code. The message interpolates the exit code (e.g. exit 1 for gh-side errors, exit 4 for missing auth in some gh versions, exit 8 for GraphQL HTTP errors). This is the generic 'gh itself reported failure' bucket before any stdout parsing happens.

Source

Thrown at scripts/star_history.py:236

        arguments = [
            "gh",
            "api",
            "graphql",
            "-f",
            f"query={GRAPHQL_QUERY}",
            "-f",
            f"owner={REPOSITORY_OWNER}",
            "-f",
            f"name={REPOSITORY_NAME}",
        ]
        if after is not None:
            if not after or "\n" in after or "\r" in after:
                raise StarHistoryError("GitHub returned an invalid pagination cursor")
            arguments.extend(("-f", f"after={after}"))

        completed = self._runner.run(arguments)
        if completed.returncode != 0:
            raise StarHistoryError(
                f"GitHub GraphQL request failed (exit {completed.returncode})"
            )
        try:
            payload = json.loads(completed.stdout)
        except json.JSONDecodeError as exc:
            raise StarHistoryError("GitHub GraphQL returned malformed JSON") from exc

        if not isinstance(payload, dict) or payload.get("errors"):
            raise StarHistoryError("GitHub GraphQL rejected the stargazer request")
        try:
            data = payload["data"]
            repository = data["repository"]
            stargazers = repository["stargazers"]
            rate_limit = data["rateLimit"]
            raw_edges = stargazers["edges"]
            page_info = stargazers["pageInfo"]
        except (KeyError, TypeError) as exc:
            raise StarHistoryError("GitHub GraphQL response had an unexpected shape") from exc

View on GitHub (pinned to b5b53acc57)

Solutions

Reproduce manually to see gh's stderr: gh api graphql -f query='<the query>' -f owner=666ghj -f name=MiroFish — the real reason is always in stderr.
Authenticate: gh auth login or export GH_TOKEN=<token> with repo read scope.
Check rate limits: gh api rate_limit; backfill pages 100 stargazers at a time, so large repos can exhaust points — wait for reset or reduce PAGE_SIZE.
Upgrade gh if the manual run shows GraphQL field errors (rateLimit/stargazers schema changed): brew upgrade gh.

Example fix

# before: error hides gh's stderr
completed = self._runner.run(arguments)
if completed.returncode != 0:
    raise StarHistoryError(
        f"GitHub GraphQL request failed (exit {completed.returncode})"
    )

# after: surface a bounded, redacted stderr snippet
if completed.returncode != 0:
    detail = completed.stderr.strip().splitlines()[:1]
    raise StarHistoryError(
        f"GitHub GraphQL request failed (exit {completed.returncode}): "
        f"{detail[0][:200] if detail else 'no stderr'}"
    )

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil, subprocess

# preflight: gh exists and is authenticated non-interactively
if shutil.which("gh") is None:
    raise SystemExit("gh not installed")
probe = subprocess.run(
    ["gh", "auth", "status"], capture_output=True, text=True, timeout=15
)
if probe.returncode != 0:
    raise SystemExit(f"gh not authenticated: {probe.stderr.strip()[:200]}")

Try / catch

try:
    page = gateway.fetch_stargazer_page(after)
except StarHistoryError as exc:
    if "GitHub GraphQL request failed (exit" in str(exc):
        # exit code is in the message; the actionable detail is in gh's stderr,
        # so reproduce the gh command manually to read it
        raise SystemExit(f"gh failed: {exc}. Run `gh auth status` and the gh "
                         "api graphql command by hand for details.")
    raise

Prevention

Always run `gh auth status` as a preflight before backfill.
Patch the raise to include a bounded slice of completed.stderr — the exit code alone is rarely actionable.
Track the exit code: exit 1 usually means auth/query error, HTTP-level failures can map to gh's documented exit codes.

When it happens

Trigger: gh not authenticated (no gh auth login / GH_TOKEN) — gh exits non-zero with 'gh auth login required'; invalid or expired token; gh api HTTP errors against api.github.com; network failure inside gh; GraphQL query field errors that gh surfaces as exit != 0.

Common situations: Running backfill on a new machine without gh auth; GH_TOKEN expired or revoked; GitHub API rate limit exhausted (gh exits non-zero on HTTP 403); gh version too old for the pinned GraphQL query shape.

Related errors

AI-assisted analysis of 666ghj/MiroFish@b5b53acc57 (2026-08-14). Data as JSON: /api/errors/01ae35def7465c4b. Report an issue: GitHub.