failed

Error message

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

What it means

runCommand throws this error when the spawned subprocess finishes with a non-zero exit status. The message includes the full command line and whatever the process wrote to stderr (falling back to stdout). It surfaces failures of underlying tools (gh, git, etc.) to the audit's caller with their own diagnostic output preserved.

Solutions

Read the stderr text in the message to see the tool's own failure reason
Re-authenticate the failing tool (e.g. `gh auth login` or set GH_TOKEN)
Run the exact command shown in the message manually to reproduce and diagnose
Fix repository/argument inputs (correct repo slug, existing resources)

Example fix

// before
const prs = runGhJson(['pr', 'list']); // fails if not authenticated
// after
if (!process.env.GH_TOKEN) {
  throw new Error('Set GH_TOKEN or run gh auth login first');
}
const prs = runGhJson(['pr', 'list']);

Defensive patterns

Strategy: retry

Validate before calling

if (!process.env.GH_TOKEN && !hasGhAuth()) {
  throw new Error('Authenticate with gh auth login or set GH_TOKEN before running');
}

Try / catch

async function runWithRetry(fn, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    try { return fn(); }
    catch (e) {
      const transient = /rate limit|timed out|network/i.test(e.message);
      if (!transient || i === attempts - 1) throw e;
      await new Promise(r => setTimeout(r, 2 ** i * 1000));
    }
  }
}

Prevention

Authenticate gh (gh auth login / GH_TOKEN) before invoking
Run failing commands manually to reproduce their stderr
Respect rate limits and add retries for transient network failures
Validate repo/argument inputs against the target environment

When it happens

Trigger: The child process runs but exits non-zero — e.g. `gh pr list` failing with an auth error, a bad repository slug, rate limiting, or network failure; any command returning an error status.

Common situations: Expired or missing GitHub credentials (`gh auth login` needed); wrong --repo or working directory; network restrictions in CI; the queried resource not existing (gh exits 1).

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/4528586105b26a21. Report an issue: GitHub.

Appendix: source

Thrown at scripts/platform-audit.js:238

    .replace(/\\/g, '/')
    .replace(/^\.\/+/, '')
    .replace(/\/+$/, '') + (String(value || '').endsWith('/') ? '/' : '');
}

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)