facebook/docusaurus · error · Error

The redirect plugin is not supposed to override existing…

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.

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.

Appendix: 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)