facebook/docusaurus · error

Missing project name. Did you forget to define "projectName"

Error message

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

What it means

Thrown by `docusaurus deploy` when the target GitHub repository name cannot be resolved. The deploy command resolves projectName from `process.env.PROJECT_NAME`, then CircleCI's `CIRCLE_PROJECT_REPONAME`, then `siteConfig.projectName`. Without it, the deployment git remote and the published site URL cannot be constructed.

Source

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

  }

  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 =
    process.env.CI_PULL_REQUEST ?? process.env.CIRCLE_PULL_REQUEST;
  if (isPullRequest) {
    exec('echo "Skipping deploy on a pull request."', {
      log: false,
      failfast: true,
    });
    process.exit(0);
  }

  // github.io indicates organization repos that deploy via default branch. All
  // others use gh-pages (either case can be configured actually, but we can

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Add `projectName: 'your-repo-name'` (the GitHub repo name, not URL) to `docusaurus.config.js`/`.ts`.
2. Export `PROJECT_NAME` in the deploy environment: `export PROJECT_NAME=your-repo-name`.
3. On CircleCI, confirm the job is a real project build so `CIRCLE_PROJECT_REPONAME` is populated.
4. Re-check that the config actually loaded is the one you edited (pass `--config` explicitly if needed).

Example fix

// before
export default { url: 'https://example.com', organizationName: 'org' };
// after
export default {
  url: 'https://org.github.io',
  organizationName: 'org',
  projectName: 'my-repo',
};

const project = process.env.PROJECT_NAME
  ?? process.env.CIRCLE_PROJECT_REPONAME
  ?? siteConfig.projectName;
if (!project) throw new Error('projectName required for deploy');

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

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

When it happens

Trigger: Running `docusaurus deploy` with `projectName` absent from `docusaurus.config.js`, no `PROJECT_NAME` env var, and not on CircleCI (or `CIRCLE_PROJECT_REPONAME` unavailable).

Common situations: Fresh project where `projectName` was never set; renamed GitHub repository without updating config; non-CircleCI CI that does not expose `CIRCLE_PROJECT_REPONAME`; local deploy run without env vars.

Related errors

• Missing project organization name. Did you forget to define
• 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/01b42b2a5befaafe. Report an issue: GitHub.