vercel-labs/agent-skills · warning · Error

output file already exists: ${outPath}. Use a fresh run dire

Error message

output file already exists: ${outPath}. Use a fresh run directory or pass --force to overwrite.

What it means

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.

Source

Thrown at skills/vercel-optimize/scripts/prepare-investigation-brief.mjs:221

    else if (a.startsWith('--group=')) out.group = a.slice('--group='.length);
    else if (a === '--out') out.outPath = resolve(argv[++i]);
    else if (a.startsWith('--out=')) out.outPath = resolve(a.slice('--out='.length));
    else if (a === '--list') out.list = true;
    else if (a === '--deterministic') out.deterministic = true;
    else if (a === '--force') out.force = true;
    else out.positional.push(a);
  }
  out.mergedPath = out.positional[0];
  out.investigationPath = out.positional[1];
  return out;
}

async function writeBriefFile(outPath, brief, { force = false } = {}) {
  try {
    await writeFile(outPath, brief + '\n', { encoding: 'utf-8', flag: force ? 'w' : 'wx' });
  } catch (err) {
    if (err?.code === 'EEXIST') {
      throw new Error(`output file already exists: ${outPath}. Use a fresh run directory or pass --force to overwrite.`);
    }
    throw err;
  }
}

main().catch((err) => {
  console.error('[prepare-brief] FAILED:', err.message);
  console.error(err.stack);
  process.exit(1);
});

View on GitHub (pinned to b8caa260a4)

Solutions

1. Pass `--force` to allow overwrite: `prepare-investigation-brief.mjs merged.json brief.md --force`.
2. Use a fresh output path or run directory for each brief.
3. Remove the stale brief file before re-running.

Example fix

# before
$ node scripts/prepare-investigation-brief.mjs run1/merged.json run1/brief.md
-> output file already exists: run1/brief.md

# after
$ node scripts/prepare-investigation-brief.mjs run1/merged.json run1/brief.md --force
# or write to a new path
$ node scripts/prepare-investigation-brief.mjs run1/merged.json run1/brief.v2.md

import { existsSync } from 'node:fs';
function assertBriefWritable(outPath, force) {
  if (existsSync(outPath) && !force) {
    throw new Error(`${outPath} exists; pass --force or choose a new path`);
  }
}
assertBriefFile(outPath, force); // before writeBriefFile

try {
  await writeBriefFile(outPath, brief, { force });
} catch (err) {
  if (err.message.startsWith('output file already exists')) {
    // resolve by passing --force or a new outPath, then retry
  } else throw err; // other I/O errors propagate
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• output file already exists: ${path}. Use a fresh run directo
• Could not read ${label} JSON at ${path}: ${err.message}
• VERCEL_NOT_INSTALLED
• VERCEL_VERSION_UNPARSEABLE
• VERCEL_CLI_TOO_OLD

AI-assisted analysis of vercel-labs/agent-skills@b8caa260a4 (2026-08-13). Data as JSON: /api/errors/27c92ed4e1f7a945. Report an issue: GitHub.