What causes "Couldn't load package.json file at ${packageJsonPath}" in facebook/docusaurus?

Validate the file: `node -e "JSON.parse(require('fs').readFileSync('package.json','utf8'))"` or use a JSON linter.

facebook/docusaurus · error · Error

Couldn't load package.json file at ${packageJsonPath}

Error message

Couldn't load package.json file at ${packageJsonPath}

What it means

Thrown by `tryLoadPackageJson` when a `package.json` file exists at the given path but `fs.readJSON` fails to parse it. The original parse error is attached as `cause`. Docusaurus reads the site's `package.json` to derive site metadata (name/version), so a malformed file aborts startup.

Source

Thrown at packages/docusaurus/src/server/siteMetadata.ts:29

import type {
  LoadedPlugin,
  PluginVersionInformation,
  SiteMetadata,
} from '@docusaurus/types';

type PackageJson = {
  name?: string;
  version?: string;
};

async function tryLoadPackageJson(
  packageJsonPath: string,
): Promise<PackageJson | undefined> {
  if (await fs.pathExists(packageJsonPath)) {
    try {
      return (await fs.readJSON(packageJsonPath)) as PackageJson;
    } catch (error) {
      throw new Error(`Couldn't load package.json file at ${packageJsonPath}`, {
        cause: error,
      });
    }
  }
  return undefined;
}

export async function tryLoadSitePackageJson(
  siteDir: string,
): Promise<PackageJson | undefined> {
  return tryLoadPackageJson(path.join(siteDir, 'package.json'));
}

export async function loadPluginVersion(
  pluginPath: string,
  siteDir: string,
): Promise<PluginVersionInformation> {
  let potentialPluginPackageJsonDirectory = path.dirname(pluginPath);

View on GitHub (pinned to 3f483e80e3)

Solutions

Validate the file: `node -e "JSON.parse(require('fs').readFileSync('package.json','utf8'))"` or use a JSON linter.
Fix the specific syntax error (the `cause` error carries the position).
Restore from version control if corrupted: `git checkout -- package.json`.

Example fix

// before (package.json, invalid)
{
  "name": "site",
  // comment is not valid JSON
  "version": "1.0.0",
}
// after
{
  "name": "site",
  "version": "1.0.0"
}

Defensive patterns

Strategy: try-catch

Validate before calling

function readPackageJsonSafe(p: string) {
  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
  catch (e) { throw new Error(`Invalid JSON in ${p}: ${(e as Error).message}`); }
}

Try / catch

try {
  const pkg = await fs.readJSON(packageJsonPath);
} catch (e) {
  console.error('package.json parse failed:', e.message);
  // restore from git or prompt user
}

Prevention

Never hand-edit package.json with JSON5 syntax.
Lint package.json in CI (`node -e "JSON.parse(...)"`).
Commit package.json so a corrupt copy can be `git checkout`-ed.

When it happens

Trigger: The site's `package.json` (or a plugin's) contains invalid JSON — trailing commas, comments, unquoted keys, or truncation. The `fs.pathExists` check passes but `fs.readJSON` throws; siteMetadata.ts:27-31 re-throws a clearer message.

Common situations: Hand-editing package.json and leaving a syntax error; a bot/tool writing JSON5 by mistake; a corrupted file from a git merge conflict; an npm script that overwrote package.json with log output.

Related errors

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