{"record":{"id":"2f39645e6cbf5fb9","repo":"vercel-labs/agent-skills","slug":"output-file-already-exists-path-use-a-fresh-r","errorCode":null,"errorMessage":"output file already exists: ${path}. 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/merge-signals.mjs","lineNumber":172,"sourceCode":"}\n\nasync function readJson(path, label) {\n  try {\n    return JSON.parse(await readFile(path, 'utf-8'));\n  } catch (err) {\n    throw new Error(`Could not read ${label} JSON at ${path}: ${err.message}`);\n  }\n}\n\nfunction assertObject(value, label) {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    throw new Error(`${label} must be a JSON object.`);\n  }\n}\n\nasync function writeOutput(path, body, { force }) {\n  if (!force && await exists(path)) {\n    throw new Error(`output file already exists: ${path}. Use a fresh run directory or pass --force to overwrite.`);\n  }\n  await mkdir(dirname(path), { recursive: true });\n  await writeFile(path, body);\n}\n\nasync function exists(path) {\n  try {\n    await access(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nif (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {\n  main().catch((err) => {\n    console.error('[merge-signals] FAILED:', err.message);\n    process.exit(1);","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/vercel-labs/agent-skills/blob/b8caa260a420a73042e35521de4b5c8baf6446cc/skills/vercel-optimize/scripts/merge-signals.mjs#L154-L190","documentation":"Thrown by writeOutput() in merge-signals.mjs when the destination path already exists and `--force` was not passed. The guard (exists() check before writeFile) prevents clobbering a previous merged result, since merges are meant to land in a fresh run directory per the skill's doctrine of reproducible artifacts.","triggerScenarios":"Re-running merge-signals into the same output path from a prior run without `--force`; an output directory reused across runs; a typo pointing -o at an existing file.","commonSituations":"Iterating on a merge and forgetting to change the output name; CI reusing a workspace without cleaning; a run directory shared between merge and prepare-brief steps.","solutions":["Pass `--force` to overwrite deliberately: `merge-signals.mjs signals.json codebase.json -o out.json --force`.","Write to a fresh run directory each invocation (recommended by the skill).","Delete or rename the stale output before re-running."],"exampleFix":"# before\n$ node scripts/merge-signals.mjs s.json c.json -o run1/merged.json\n-> output file already exists: run1/merged.json\n\n# after\n$ node scripts/merge-signals.mjs s.json c.json -o run2/merged.json\n# or\n$ node scripts/merge-signals.mjs s.json c.json -o run1/merged.json --force","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nfunction assertOutputWritable(path, force) {\n  if (existsSync(path) && !force) {\n    throw new Error(`${path} exists; pass --force or use a fresh run directory`);\n  }\n}\nassertOutputWritable(outPath, args.force);","typeGuard":null,"tryCatchPattern":"try {\n  await writeOutput(outPath, body, { force });\n} catch (err) {\n  if (err.message.startsWith('output file already exists')) {\n    // either pass --force or pick a new path, then retry\n  }\n  throw err;\n}","preventionTips":["Write each merge to a fresh run directory.","Pass --force only when intentionally overwriting.","Clean CI workspaces between runs."],"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"}