{"record":{"id":"27c92ed4e1f7a945","repo":"vercel-labs/agent-skills","slug":"output-file-already-exists-outpath-use-a-fres","errorCode":null,"errorMessage":"output file already exists: ${outPath}. Use a fresh run directory or pass --force to overwrite.","messagePattern":"output file already exists: (.+?)\\. Use a fresh run directory or pass --force to overwrite\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"skills/vercel-optimize/scripts/prepare-investigation-brief.mjs","lineNumber":221,"sourceCode":"    else if (a.startsWith('--group=')) out.group = a.slice('--group='.length);\n    else if (a === '--out') out.outPath = resolve(argv[++i]);\n    else if (a.startsWith('--out=')) out.outPath = resolve(a.slice('--out='.length));\n    else if (a === '--list') out.list = true;\n    else if (a === '--deterministic') out.deterministic = true;\n    else if (a === '--force') out.force = true;\n    else out.positional.push(a);\n  }\n  out.mergedPath = out.positional[0];\n  out.investigationPath = out.positional[1];\n  return out;\n}\n\nasync function writeBriefFile(outPath, brief, { force = false } = {}) {\n  try {\n    await writeFile(outPath, brief + '\\n', { encoding: 'utf-8', flag: force ? 'w' : 'wx' });\n  } catch (err) {\n    if (err?.code === 'EEXIST') {\n      throw new Error(`output file already exists: ${outPath}. Use a fresh run directory or pass --force to overwrite.`);\n    }\n    throw err;\n  }\n}\n\nmain().catch((err) => {\n  console.error('[prepare-brief] FAILED:', err.message);\n  console.error(err.stack);\n  process.exit(1);\n});\n","sourceCodeStart":203,"sourceCodeEnd":232,"githubUrl":"https://github.com/vercel-labs/agent-skills/blob/b8caa260a420a73042e35521de4b5c8baf6446cc/skills/vercel-optimize/scripts/prepare-investigation-brief.mjs#L203-L232","documentation":"Thrown by writeBriefFile() in prepare-investigation-brief.mjs when writeFile with flag 'wx' fails with EEXIST — i.e. the output path already exists and `--force` was not set. The 'wx' flag atomically refuses to create over an existing file, which is the same protection as merge-signals' exists() check but implemented at the syscall level. It rethrows only EEXIST as the friendly message and propagates other I/O errors untouched.","triggerScenarios":"Re-running prepare-brief into the same brief path; an output path colliding with an existing file in the run directory; CI workspace not cleaned between runs.","commonSituations":"Iterating on the brief without bumping the output name; a shared run dir between merge and brief; re-running after a partial failure left the file behind.","solutions":["Pass `--force` to allow overwrite: `prepare-investigation-brief.mjs merged.json brief.md --force`.","Use a fresh output path or run directory for each brief.","Remove the stale brief file before re-running."],"exampleFix":"# before\n$ node scripts/prepare-investigation-brief.mjs run1/merged.json run1/brief.md\n-> output file already exists: run1/brief.md\n\n# after\n$ node scripts/prepare-investigation-brief.mjs run1/merged.json run1/brief.md --force\n# or write to a new path\n$ node scripts/prepare-investigation-brief.mjs run1/merged.json run1/brief.v2.md","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nfunction assertBriefWritable(outPath, force) {\n  if (existsSync(outPath) && !force) {\n    throw new Error(`${outPath} exists; pass --force or choose a new path`);\n  }\n}\nassertBriefFile(outPath, force); // before writeBriefFile","typeGuard":null,"tryCatchPattern":"try {\n  await writeBriefFile(outPath, brief, { force });\n} catch (err) {\n  if (err.message.startsWith('output file already exists')) {\n    // resolve by passing --force or a new outPath, then retry\n  } else throw err; // other I/O errors propagate\n}","preventionTips":["Use a unique brief filename per run.","Pass --force when deliberately regenerating a brief.","Remove stale briefs when reusing a run directory."],"tags":["filesystem","io","safety","vercel"],"backgroundTag":null,"analyzedSha":"b8caa260a420a73042e35521de4b5c8baf6446cc","analyzedAt":"2026-08-13T06:03:29.508Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}