facebook/docusaurus · error

Missing project organization name. Did you forget to define

Error message

Missing project organization name. Did you forget to define "organizationName" in ${siteConfigPath}? You may also export it via the ORGANIZATION_NAME environment variable.

What it means

Thrown by `docusaurus deploy` when it cannot resolve the GitHub organization/user that owns the deployment target repository. The deploy command resolves organizationName from three sources in order: the `ORGANIZATION_NAME` env var, the CircleCI-provided `CIRCLE_PROJECT_USERNAME`, then `siteConfig.organizationName`. If all three are unset/empty, deployment cannot proceed because the git remote URL and final website URL cannot be computed.

Source

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

    process.env.USE_SSH.toLowerCase() === 'true';

  if (!gitUser && !useSSH) {
    // If USE_SSH is unspecified: try inferring from repo URL
    if (process.env.USE_SSH === undefined && hasSSHProtocol(sourceRepoUrl)) {
      useSSH = true;
    } else {
      throw new Error(
        'Please set the GIT_USER environment variable, or explicitly specify USE_SSH instead!',
      );
    }
  }

  const organizationName =
    process.env.ORGANIZATION_NAME ??
    process.env.CIRCLE_PROJECT_USERNAME ??
    siteConfig.organizationName;
  if (!organizationName) {
    throw new Error(
      `Missing project organization name. Did you forget to define "organizationName" in ${siteConfigPath}? You may also export it via the ORGANIZATION_NAME environment variable.`,
    );
  }
  logger.info`organizationName: name=${organizationName}`;

  const projectName =
    process.env.PROJECT_NAME ??
    process.env.CIRCLE_PROJECT_REPONAME ??
    siteConfig.projectName;
  if (!projectName) {
    throw new Error(
      `Missing project name. Did you forget to define "projectName" in ${siteConfigPath}? You may also export it via the PROJECT_NAME environment variable.`,
    );
  }
  logger.info`projectName: name=${projectName}`;

  // We never deploy on pull request.
  const isPullRequest =

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Add `organizationName: 'your-github-user-or-org'` to the exported config object in `docusaurus.config.js`/`.ts`.
2. Export `ORGANIZATION_NAME` in your shell or CI environment: `export ORGANIZATION_NAME=your-github-user-or-org`.
3. If on CircleCI, ensure the job has access to the built-in `CIRCLE_PROJECT_USERNAME` env var (it is set automatically for project builds).
4. Verify the config file you are deploying with is the one being loaded (use `--config` if you have multiple).

Example fix

// before (docusaurus.config.js)
export default {
  url: 'https://example.com',
  // organizationName missing
};
// after
export default {
  url: 'https://your-org.github.io',
  organizationName: 'your-org',
  projectName: 'your-site',
};

// before deploy: assert organizationName is resolvable
import fs from 'fs-extra';
const org = process.env.ORGANIZATION_NAME
  ?? process.env.CIRCLE_PROJECT_USERNAME
  ?? (await import('./docusaurus.config.js')).default.organizationName;
if (!org) {
  throw new Error('Set organizationName in config or ORGANIZATION_NAME env before deploy.');
}

function hasOrganizationName(cfg: any): cfg is { organizationName: string } {
  return typeof cfg?.organizationName === 'string' && cfg.organizationName.length > 0;
}

try {
  await deploy(siteDir, cliOptions);
} catch (e) {
  if (/Missing project organization name/.test(e.message)) {
    console.error('Set ORGANIZATION_NAME env or config.organizationName');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Running `docusaurus deploy` (or `deploy` CLI command) without `organizationName` in `docusaurus.config.js`, without the `ORGANIZATION_NAME` env var, and outside CircleCI (so `CIRCLE_PROJECT_USERNAME` is also unset).

Common situations: New project forgetting to fill in `organizationName`; running deploy locally for the first time without env vars; CI provider other than CircleCI that does not set `CIRCLE_PROJECT_USERNAME`; config file accidentally deleted/overwritten the field.

Related errors

• Missing project name. Did you forget to define "projectName"
• For GitHub pages organization deployments, 'docusaurus deplo
• Please set the GIT_USER environment variable, or explicitly
• Unknown Docusaurus VCS preset name: ${process.env.DOCUSAURUS
• Git not installed or not added to PATH!

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