failed

Error message

${command} ${args.join(' ')} failed: ${(result.stderr || result.stdout || '').trim()}

What it means

runCommand throws this when the spawned command completed but exited with a non-zero status. The error message includes the command line plus whatever the child wrote to stderr (falling back to stdout if stderr is empty). This is the normal 'gh CLI rejected the request' path, e.g. auth failures, network errors, or missing repos.

Solutions

Read the stderr portion of the message for gh's specific complaint and fix accordingly.
Authenticate: run `gh auth login` or set GH_TOKEN/GITHUB_TOKEN in the environment.
Verify the repository string and arguments (owner/name correct, repo exists, you have access).
For rate limits, wait for the reset window or use a token with a higher quota.

Example fix

// before
const data = runGhJson(['api', 'repos/o/r']);

// after
try {
  const data = runGhJson(['api', 'repos/o/r']);
} catch (e) {
  if (!process.env.GH_TOKEN && !process.env.GITHUB_TOKEN) {
    throw new Error('Set GH_TOKEN before calling GitHub APIs');
  }
  throw e;
}

Defensive patterns

Strategy: retry

Validate before calling

const authed = !!(process.env.GH_TOKEN || process.env.GITHUB_TOKEN) || spawnSync('gh', ['auth', 'status']).status === 0;
if (!authed) throw new Error('gh is not authenticated');

Try / catch

try {
  const out = runGhJson(args);
} catch (e) {
  if (/rate limit/i.test(e.message)) {
    await sleep(60_000);
    return runGhJson(args); // retry once
  }
  throw e;
}

Prevention

Set GH_TOKEN/GITHUB_TOKEN in CI and run `gh auth login` locally.
Validate repo/argument values before invoking gh to avoid 404/422 noise.
Retry only transient failures (rate limits, network), never auth or not-found errors.

When it happens

Trigger: Any runCommand/runGhJson call where gh exits non-zero: unauthenticated gh (no GH_TOKEN and no login), nonexistent repository (404), rate limiting, bad arguments passed in args, or network failures reported by gh on stderr.

Common situations: CI job missing a GH_TOKEN/GITHUB_TOKEN; gh never authenticated locally (`gh auth login` not run); typo in repo owner/name; enterprise hosts requiring GH_HOST; expired session.

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 affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/291f867d5a67ff41. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/github-discussions.js:31

    throw new Error(`Invalid repo: ${repo}`);
  }
  return { owner, name };
}

function runCommand(command, args, options = {}) {
  const result = spawnSync(command, args, {
    cwd: options.cwd,
    env: options.env || process.env,
    encoding: 'utf8',
    maxBuffer: 10 * 1024 * 1024,
  });

  if (result.error) {
    throw new Error(`${command} ${args.join(' ')} failed: ${result.error.message}`);
  }

  if (result.status !== 0) {
    throw new Error(`${command} ${args.join(' ')} failed: ${(result.stderr || result.stdout || '').trim()}`);
  }

  return result.stdout || '';
}

function runGhJson(args, options = {}) {
  const shimPath = process.env.ECC_GH_SHIM;
  const command = shimPath ? process.execPath : 'gh';
  const commandArgs = shimPath ? [shimPath, ...args] : args;
  const env = { ...process.env };

  if (!options.useEnvGithubToken) {
    delete env.GITHUB_TOKEN;
  }

  const stdout = runCommand(command, commandArgs, { env });
  try {
    return JSON.parse(stdout || 'null');

View on GitHub (pinned to 8321021c54)