{"record":{"id":"0a019283d2e31ce6","repo":"facebook/docusaurus","slug":"the-redirect-plugin-is-not-supposed-to-override-ex","errorCode":null,"errorMessage":"The redirect plugin is not supposed to override existing files.","messagePattern":"The redirect plugin is not supposed to override existing files\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-plugin-client-redirects/src/writeRedirectFiles.ts","lineNumber":94,"sourceCode":"    const fileRelativePath = getRedirectFilePath(redirect.from, trailingSlash);\n    const fileAbsolutePath = path.join(pluginContext.outDir, fileRelativePath);\n    const toUrl = createToUrl(pluginContext.baseUrl, redirect.to);\n    const fileContent = createPageContentMemoized(toUrl);\n    return {\n      ...redirect,\n      fileAbsolutePath,\n      fileContent,\n    };\n  };\n\n  return redirects.map(createFileMetadata);\n}\n\nexport async function writeRedirectFile(file: RedirectFile): Promise<void> {\n  try {\n    // User-friendly security to prevent file overrides\n    if (await fs.pathExists(file.fileAbsolutePath)) {\n      throw new Error(\n        'The redirect plugin is not supposed to override existing files.',\n      );\n    }\n    await fs.outputFile(\n      file.fileAbsolutePath,\n      file.fileContent,\n      // Hard security to prevent file overrides\n      // See https://stackoverflow.com/a/34187712/82609\n      {flag: 'wx'},\n    );\n  } catch (err) {\n    logger.error`Redirect file creation error for path=${file.fileAbsolutePath}.`;\n    throw err;\n  }\n}\n\nexport default async function writeRedirectFiles(\n  redirectFiles: RedirectFile[],","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-plugin-client-redirects/src/writeRedirectFiles.ts#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import fs from 'fs-extra';\nimport path from 'path';\n// Before build, check that no redirect output path collides with existing files\nconst collisions = redirects.filter(r => fs.pathExistsSync(path.join(outDir, r.from)));\nif (collisions.length) console.warn('Redirect collisions:', collisions);","typeGuard":null,"tryCatchPattern":"try {\n  await writeRedirectFile(file);\n} catch (err) {\n  if (/not supposed to override existing files/.test((err as Error).message)) {\n    // remove stale target or rename redirect, then retry once\n  } else throw err;\n}","preventionTips":["Run docusaurus clear between major config changes.","Keep redirect 'from' paths disjoint from real routes."],"tags":["redirects","filesystem","build","safety-guard"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}