facebook/docusaurus · error

You cannot deploy from this branch (${sourceBranch}). You wi

Error message

You cannot deploy from this branch (${sourceBranch}).
You will need to checkout to a different branch!

What it means

Thrown by `docusaurus deploy` when the branch you are currently on (`sourceBranch`) equals the deployment branch and this is not a cross-repo publish. Docusaurus refuses to push build output onto the branch it just built from, because that would overwrite the source tree. Cross-repo publishes (where the source repo differs from the deploy repo) are exempt.

Source

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

    deploymentRepoURL = buildHttpsUrl(
      gitCredentials,
      githubHost,
      organizationName,
      projectName,
      githubPort,
    );
  }

  logger.info`Remote repo URL: name=${obfuscateGitPass(deploymentRepoURL)}`;

  // Check if this is a cross-repo publish.
  const crossRepoPublish = !sourceRepoUrl.endsWith(
    `${organizationName}/${projectName}.git`,
  );

  // We don't allow deploying to the same branch unless it's a cross publish.
  if (sourceBranch === deploymentBranch && !crossRepoPublish) {
    throw new Error(
      `You cannot deploy from this branch (${sourceBranch}).` +
        '\nYou will need to checkout to a different branch!',
    );
  }

  // Save the commit hash that triggers publish-gh-pages before checking
  // out to deployment branch.
  const currentCommit = exec('git rev-parse HEAD')?.stdout?.toString().trim();

  const runDeploy = async (outputDirectory: string) => {
    const targetDirectory = cliOptions.targetDir ?? '.';
    const fromPath = outputDirectory;
    const toPath = await fs.mkdtemp(
      path.join(os.tmpdir(), `${projectName}-${deploymentBranch}`),
    );
    process.chdir(toPath);

    // Clones the repo into the temp folder and checks out the target branch.

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Checkout your source branch first: `git checkout main` (or `master`), then re-run `docusaurus deploy`.
2. If you intentionally deploy from a non-default branch, set `deploymentBranch` to a different value (e.g. `gh-pages`) so the two differ.
3. For a cross-repo setup, ensure the source repo URL does not match `${organizationName}/${projectName}.git` (use a separate deploy repo).
4. In CI, verify the checkout step pulls the source branch, not the deployment branch.

Example fix

# before: on gh-pages, deploying to gh-pages
git branch # -> * gh-pages
docusaurus deploy  # throws
# after
git checkout main
docusaurus deploy

import {execSync} from 'child_process';
const sourceBranch = execSync('git rev-parse --abbrev-ref HEAD').toString().trim();
if (sourceBranch === deploymentBranch && !isCrossRepo) {
  throw new Error(`Switch off ${sourceBranch} before deploying to it`);
}

function isSafeToDeploy(sourceBranch: string, deploymentBranch: string, crossRepo: boolean): boolean {
  return crossRepo || sourceBranch !== deploymentBranch;
}

try { await deploy(siteDir, cliOptions); }
catch (e) {
  if (/cannot deploy from this branch/i.test(e.message)) {
    console.error('Checkout your source branch first (e.g. git checkout main)'); process.exit(1);
  }
  throw e;
}

When it happens

Trigger: `sourceBranch === deploymentBranch` AND `sourceRepoUrl` still ends with `${organizationName}/${projectName}.git` (i.e. not a cross-repo deploy). Typical example: you are on `gh-pages` and try to deploy to `gh-pages`.

Common situations: Switched into the deployment branch by accident before running deploy; set `deploymentBranch` to your working branch; cloned and forgot to checkout `main`/`master` first; CI checked out the deploy branch.

Related errors

• Please set the GIT_USER environment variable, or explicitly
• For GitHub pages organization deployments, 'docusaurus deplo
• Running "git push" command failed. Does the GitHub user acco
• Command returned unexpected exitCode ${result.exitCode}
• Error while executing command code=${obfuscateGitPass(cmd)}

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