Processing of page source file path=${relativeSource} failed

Error message

Processing of page source file path=${relativeSource} failed.

What it means

Thrown by loadPagesContent in the pages plugin as a wrapper around any failure while processing an individual page source file (processPageSourceFile). The original error is attached via Error options.cause. It surfaces during content loading (build/dev) and names the relative source path that failed, so the underlying cause must be inspected.

Source

Thrown at packages/docusaurus-plugin-content-pages/src/content.ts:81

  options: PluginOptions;
  contentPaths: ContentPaths;
};

export async function loadPagesContent(
  params: LoadContentParams,
): Promise<LoadedContent> {
  const {options} = params;

  const pagesFiles = await Globby(params.options.include, {
    cwd: params.contentPaths.contentPath,
    ignore: options.exclude,
  });

  async function doProcessPageSourceFile(relativeSource: string) {
    try {
      return await processPageSourceFile(relativeSource, params);
    } catch (err) {
      throw new Error(
        `Processing of page source file path=${relativeSource} failed.`,
        {cause: err},
      );
    }
  }

  return (await Promise.all(pagesFiles.map(doProcessPageSourceFile))).filter(
    (res): res is Metadata => {
      return res !== undefined;
    },
  );
}

async function processPageSourceFile(
  relativeSource: string,
  params: LoadContentParams,
): Promise<Metadata | undefined> {
  const {context, options, contentPaths} = params;

View on GitHub (pinned to 3f483e80e3)

Solutions

Look at err.cause (the wrapped error) for the real failure and fix that page.
Open the relative path named in the message and check MDX syntax, front matter, and imports.
Run `docusaurus start` / build again after fixing; if cause is unclear, reproduce by processing just that file.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await loadPagesContent(params);
} catch (err) {
  const cause = (err as Error & {cause?: Error}).cause;
  console.error('Page failed:', err.message, '\nRoot cause:', cause?.message);
  // fix the offending page source, then rebuild
}

Prevention

Lint MDX/front matter before build (remark/rehype).
Keep page imports resolvable; run typecheck on .mdx where possible.
Treat any wrapped 'cause' error as the source of truth, not the wrapper message.

When it happens

Trigger: Any unhandled exception from reading/parsing a page: invalid MDX, bad front matter, missing imported component, file read error, bad editUrl function, or a syntax error in a .md/.mdx/.jsx page file.

Common situations: Broken MDX in a page; front matter that fails validatePageFrontMatter; an import in an MDX page that resolves to nothing; permission/ENONENT on the source file; a custom remark/rehype plugin throwing.

Related errors

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