Workflow '${slug}' already exists at ${destPath}. Use --forc

Error message

Workflow '${slug}' already exists at ${destPath}.
Use --force to overwrite.

What it means

Collision guard: installing would overwrite an existing workflow file at `.archon/workflows/<slug>.yaml` without explicit permission. The command refuses and tells the user to pass `--force`, protecting locally modified workflows from being silently clobbered by a marketplace re-install.

Source

Thrown at packages/cli/src/commands/workflow.ts:5198

  slug: string,
  archonDir: string,
  force: boolean | undefined,
  existsSync: (p: string) => boolean,
  mkdirSync: (p: string, opts: { recursive: boolean }) => void,
  writeFileSync: (p: string, data: string) => void
): Promise<void> {
  const { owner, repo, path } = parseGitHubUrl(entry.sourceUrl);
  const content = await downloadRawFile(owner, repo, path, entry.sha);

  if (!content.trim()) {
    throw new Error(`Downloaded YAML is empty for '${slug}'`);
  }

  const workflowsDir = join(archonDir, 'workflows');
  const destPath = join(workflowsDir, `${slug}.yaml`);

  if (existsSync(destPath) && !force) {
    throw new Error(`Workflow '${slug}' already exists at ${destPath}.\nUse --force to overwrite.`);
  }

  mkdirSync(workflowsDir, { recursive: true });
  writeFileSync(destPath, content);
  console.log(`Installed '${entry.name}' to ${destPath}`);
}

async function installDirectory(
  entry: MarketplaceEntryJson,
  slug: string,
  archonDir: string,
  force: boolean | undefined,
  existsSync: (p: string) => boolean,
  mkdirSync: (p: string, opts: { recursive: boolean }) => void,
  writeFileSync: (p: string, data: string) => void
): Promise<void> {
  const { owner, repo, path } = parseGitHubUrl(entry.sourceUrl);
  const items = await fetchGitHubDirectory(owner, repo, path, entry.sha);

View on GitHub (pinned to 0773b97458)

Solutions

Re-run with `--force` if you are sure you want to overwrite: `archon workflow install <slug> --force`
Back up the existing `.archon/workflows/<slug>.yaml` first if you customized it
Pick a different local workflow name / remove the stale file
Skip the install if the existing workflow is already current

Example fix

// before
archon workflow install code-review
// after (intentional overwrite)
archon workflow install code-review --force

Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync } from 'node:fs';
const dest = join(repoRoot, '.archon', 'workflows', `${slug}.yaml`);
if (existsSync(dest) && !process.argv.includes('--force')) {
  console.error(`${dest} exists; re-run with --force to overwrite`);
  process.exit(1);
}

Try / catch

try {
  await workflowInstallCommand(slug);
} catch (e) {
  if (e instanceof Error && e.message.includes('already exists')) {
    // prompt user or re-invoke with force: true after backup
  } else throw e;
}

Prevention

Back up customized `.archon/workflows/<slug>.yaml` before reinstalling
Make install scripts idempotent by passing --force deliberately
Avoid two marketplace entries sharing a slug
Treat this error as a signal you may be overwriting local edits

When it happens

Trigger: `installSingleWorkflowFile` finds `existsSync(destPath)` true and `force` is false — i.e. re-running install for a slug already installed, or a different workflow whose slug maps to an existing filename.

Common situations: Re-running an install script that already succeeded once; installing a marketplace workflow over a locally customized one; two marketplace entries sharing a slug; leftover file from an uninstalled workflow.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/0559820de86ec8f8. Report an issue: GitHub.