facebook/docusaurus · error · Error

The redirect plugin is not supposed to override existing fil

Error message

The redirect plugin is not supposed to override existing files.

What it means

Thrown by writeRedirectFile as a user-friendly guard before writing a generated redirect file, when the target path already exists. It is backed by a second hard guard using fs.outputFile with flag 'wx' (which fails if the file exists). The intent is to never silently overwrite content the user authored.

Source

Thrown at packages/docusaurus-plugin-client-redirects/src/writeRedirectFiles.ts:94

    const fileRelativePath = getRedirectFilePath(redirect.from, trailingSlash);
    const fileAbsolutePath = path.join(pluginContext.outDir, fileRelativePath);
    const toUrl = createToUrl(pluginContext.baseUrl, redirect.to);
    const fileContent = createPageContentMemoized(toUrl);
    return {
      ...redirect,
      fileAbsolutePath,
      fileContent,
    };
  };

  return redirects.map(createFileMetadata);
}

export async function writeRedirectFile(file: RedirectFile): Promise<void> {
  try {
    // User-friendly security to prevent file overrides
    if (await fs.pathExists(file.fileAbsolutePath)) {
      throw new Error(
        'The redirect plugin is not supposed to override existing files.',
      );
    }
    await fs.outputFile(
      file.fileAbsolutePath,
      file.fileContent,
      // Hard security to prevent file overrides
      // See https://stackoverflow.com/a/34187712/82609
      {flag: 'wx'},
    );
  } catch (err) {
    logger.error`Redirect file creation error for path=${file.fileAbsolutePath}.`;
    throw err;
  }
}

export default async function writeRedirectFiles(
  redirectFiles: RedirectFile[],

View on GitHub (pinned to 3f483e80e3)

Solutions

Find the file reported in the logger.error line that follows and delete or relocate it.
Audit redirect 'from'/'to' pairs for collisions with existing generated routes.
Clear the build output directory (docusaurus clear) and rebuild.

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs-extra';
import path from 'path';
// Before build, check that no redirect output path collides with existing files
const collisions = redirects.filter(r => fs.pathExistsSync(path.join(outDir, r.from)));
if (collisions.length) console.warn('Redirect collisions:', collisions);

Try / catch

try {
  await writeRedirectFile(file);
} catch (err) {
  if (/not supposed to override existing files/.test((err as Error).message)) {
    // remove stale target or rename redirect, then retry once
  } else throw err;
}

Prevention

Run docusaurus clear between major config changes.
Keep redirect 'from' paths disjoint from real routes.

When it happens

Trigger: A redirect target path collides with an existing file in the build output dir, or two redirect entries resolve to the same output file. Also happens when a hand-authored HTML/static file already lives at the redirect output location.

Common situations: A redirect 'to' points to a path that a docs/blog/page plugin also emits, or the build output directory has stale files from a prior config. Renaming routes while keeping old redirect config can also collide.

Related errors

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