failed

Error message

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

What it means

runCommand throws when the spawned command (gh or shim) exits with a non-zero status. The message embeds stderr (or stdout) from the child, forwarding the underlying gh error — e.g. authentication failures, not-found resources, or network errors. It is the pass-through path for any gh CLI failure.

Solutions

Read the stderr in the message to identify the underlying gh failure and fix that cause.
Run `gh auth status` and authenticate with `gh auth login` or set GH_TOKEN.
Verify the repo slug (owner/name) and that you have access to it.
Check network connectivity and GitHub API rate-limit status, then retry.

Example fix

// before
runGh(['issue', 'view', '123', '-R', 'org/typo-repo']);
// after
// verify repo exists first: gh repo view org/correct-repo
runGh(['issue', 'view', '123', '-R', 'org/correct-repo']);

Defensive patterns

Strategy: try-catch

Validate before calling

const auth = require('child_process').spawnSync('gh', ['auth', 'status'], { encoding: 'utf8' });
if (auth.status !== 0) throw new Error('gh is not authenticated; run `gh auth login` or set GH_TOKEN');

Type guard

null

Try / catch

try {
  const out = runGh(args);
} catch (e) {
  if (/failed: /.test(e.message)) {
    const stderr = e.message.split('failed: ')[1] || '';
    if (stderr.includes('auth') || stderr.includes('401')) console.error('Re-authenticate: gh auth login');
    else if (stderr.includes('404')) console.error('Check repo slug and permissions');
    else console.error('gh failed:', stderr);
  } else { throw e; }
}

Prevention

Authenticate in CI with GH_TOKEN secret before running scripts.
Verify repo slugs with `gh repo view <owner>/<name>`.
Log full stderr from the error message to diagnose the root cause.
Retry transient network errors with backoff.

When it happens

Trigger: Any runGh call where gh exits non-zero: expired/missing auth (`gh auth` not run), the issue/repo does not exist, no network access, or insufficient permissions on a private repo.

Common situations: Running in CI without `gh auth login` / GH_TOKEN set, referencing a repo slug with a typo, hitting rate limits, or a VPN/firewall blocking api.github.com.

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/c54aae4c93c65197. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/github-coordination/gh-api.js:49

function normalizeLabels(labels) {
  return Array.from(new Set((Array.isArray(labels) ? labels : []).map(normalizeLabelValue).filter(Boolean))).sort();
}

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 || '';
}

// ECC_GH_SHIM creates a trust boundary: when set, shimPath replaces the real
// `gh` binary and command/commandArgs execute an arbitrary script via
// process.execPath. This variable MUST only be set in trusted, isolated test
// environments (e.g., a test's own temp directory). Never set ECC_GH_SHIM in
// production — doing so allows arbitrary script execution under the caller's
// privileges.
function runGh(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.stripGithubToken) {

View on GitHub (pinned to 8321021c54)