facebook/docusaurus · error · Error

Can't process doc metadata for doc at path path=${args.docFi

Error message

Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}

What it means

Wrapper thrown by processDocMetadata when the inner doProcessDocMetadata rejects for any reason (parsing, slug, edit URL, tags, etc.). The original error is attached via {cause: err}. The message identifies the doc file path and version so you can locate the offending file; consult err.cause for the real reason.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/docs.ts:259

    lastUpdatedBy: lastUpdate.lastUpdatedBy,
    lastUpdatedAt: lastUpdate.lastUpdatedAt,
    sidebarPosition,
    frontMatter,
  };
}

export async function processDocMetadata(args: {
  docFile: DocFile;
  versionMetadata: VersionMetadata;
  context: LoadContext;
  options: MetadataOptions;
  env: DocEnv;
  tagsFile: TagsFile | null;
}): Promise<DocMetadataBase> {
  try {
    return await doProcessDocMetadata(args);
  } catch (err) {
    throw new Error(
      `Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`,
      {cause: err},
    );
  }
}

function getUnlistedIds(docs: DocMetadataBase[]): Set<string> {
  return new Set(docs.filter((doc) => doc.unlisted).map((doc) => doc.id));
}

export function addDocNavigation({
  docs,
  sidebarsUtils,
}: {
  docs: DocMetadataBase[];
  sidebarsUtils: SidebarsUtils;
}): LoadedVersion['docs'] {
  const docsById = createDocsByIdIndex(docs);

View on GitHub (pinned to 3f483e80e3)

Solutions

Inspect err.cause for the underlying error and fix it.
Open the doc file path printed in the message.
Re-run the build; sibling docs are processed independently.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await processDocMetadata(args);
} catch (err) {
  const cause = (err as Error & {cause?: Error}).cause;
  console.error(`Doc ${args.docFile.filePath} failed:`, cause ?? err);
}

Prevention

Read err.cause to find the real metadata failure.
Lint doc front matter (id, slug, tags) before building.

When it happens

Trigger: Any failure building a doc's metadata: bad front matter, invalid slug, error 36 (id with slash), tags file resolution error, or markdown parse failure. All are funneled through this wrapper.

Common situations: A newly added doc with broken front matter, an id containing '/', a missing referenced tags file, or a vcs/editUrl callback that throws.

Related errors

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