facebook/docusaurus · error

Command returned unexpected exitCode ${result.exitCode}

Error message

Command returned unexpected exitCode ${result.exitCode}

What it means

Thrown by the deploy command's internal `exec` helper when failfast is true and a command returned a non-zero exitCode. The offending command and its code are already logged before the throw. Used for critical git probes in deploy (e.g. `git remote get-url origin`, `git rev-parse --abbrev-ref HEAD`).

Source

Thrown at packages/docusaurus/src/commands/deploy.ts:50

// for example: https://github.com/facebook/docusaurus/issues/3875
function exec(cmd: string, options?: {log?: boolean; failfast?: boolean}) {
  const log = options?.log ?? true;
  const failfast = options?.failfast ?? false;
  try {
    // TODO migrate to execa(file,[...args]) instead
    //  Use async/await everything
    //  Avoid execa.command: the args need to be escaped manually
    const result = execa.commandSync(cmd);
    if (log || debugMode) {
      logger.info`code=${obfuscateGitPass(
        cmd,
      )} subdue=${`code: ${result.exitCode}`}`;
    }
    if (debugMode) {
      console.log(result);
    }
    if (failfast && result.exitCode !== 0) {
      throw new Error(
        `Command returned unexpected exitCode ${result.exitCode}`,
      );
    }
    return result;
  } catch (err) {
    throw new Error(
      logger.interpolate`Error while executing command code=${obfuscateGitPass(
        cmd,
      )}
In CWD code=${process.cwd()}`,
      {cause: err},
    );
  }
}

// Execa escape args and add necessary quotes automatically
// When using Execa.command, the args containing spaces must be escaped manually
function escapeArg(arg: string): string {

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Reproduce the exact logged command manually to see the underlying git error.
2. For missing origin: `git remote add origin <url>`.
3. For detached HEAD in CI: set the CURRENT_BRANCH env var to the deploying branch.
4. Ensure git credentials/SSH agent are available for any authenticated remote operation.

Example fix

# before
# deploy fails: `git remote get-url origin` exitCode=128
# after
git remote add origin git@github.com:org/repo.git
docusaurus deploy

import {execSync} from 'child_process';
function preflight(cmd: string, cwd = process.cwd()) {
  execSync(cmd, {cwd, stdio: 'pipe'}); // throws before deploy if it would fail
}

try {
  exec('git remote get-url origin', {log: false, failfast: true});
} catch (e) {
  if (/unexpected exitCode/.test(String(e))) repairOriginRemote();
  else throw e;
}

When it happens

Trigger: Any failfast exec returning non-zero during deploy: missing 'origin' remote, detached HEAD with no CURRENT_BRANCH set, or git refusing an operation (auth, permissions).

Common situations: Repo with no `origin` remote configured, shallow/detached HEAD in CI without CURRENT_BRANCH env, or git authentication failures on the source remote.

Related errors

• Error while executing command code=${obfuscateGitPass(cmd)}
• Failed to retrieve the git history for file "${file}" with e
• Git not installed or not added to PATH!
• Please set the GIT_USER environment variable, or explicitly
• You cannot deploy from this branch (${sourceBranch}). You wi

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/c4517e38f0618425. Report an issue: GitHub.