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

Error message

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

What it means

The Archon CLI workflow installer refuses to overwrite an existing workflow YAML file unless the caller explicitly passes --force. existsSync(destWorkflow) detects a file at the target path and throws this error to protect an existing workflow from silent clobbering. It is an intentional safety gate, not a failure of the install itself.

Source

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

  const items = await fetchGitHubDirectory(owner, repo, path, entry.sha);

  // Identify the main workflow YAML (named <slug>.yaml or the only .yaml in root)
  const yamlFiles = items.filter(f => f.type === 'file' && f.name.endsWith('.yaml'));
  const mainYaml =
    yamlFiles.find(f => f.name === `${slug}.yaml`) ??
    (yamlFiles.length === 1 ? yamlFiles[0] : undefined);

  if (!mainYaml) {
    throw new Error(
      `Cannot identify main workflow YAML in directory. Expected '${slug}.yaml' or a single .yaml file.`
    );
  }

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

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

  // Install the main workflow YAML
  const mainContent = await downloadRawFile(owner, repo, mainYaml.path, entry.sha);
  mkdirSync(workflowsDir, { recursive: true });
  writeFileSync(destWorkflow, mainContent);
  console.log(`  Workflow: ${destWorkflow}`);

  // Install supporting files by convention
  const subdirs = items.filter(f => f.type === 'dir');
  let installedCount = 1;

  for (const subdir of subdirs) {
    if (!isSafePathComponent(subdir.name)) {
      console.log(`  Skipped (unsafe directory name): ${subdir.name}`);
      continue;

View on GitHub (pinned to 0773b97458)

Solutions

Delete or rename the existing workflow file at the printed destination path if it is no longer wanted.
Re-run the install command with --force to intentionally overwrite the existing workflow.
Pick a different slug/name for the workflow being installed so it does not collide.

Example fix

// before
archon workflow install owner/repo
// Error: Workflow 'code-review' already exists...
// after
archon workflow install owner/repo --force

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';
const dest = join(archonDir, 'workflows', `${slug}.yaml`);
if (existsSync(dest) && process.argv.includes('--force') === false) {
  console.warn(`Skipping install: ${dest} exists. Re-run with --force or remove the file.`);
  process.exit(0);
}

Try / catch

try {
  await installWorkflow(slug, { force });
} catch (err) {
  if (err instanceof Error && err.message.includes('already exists') && err.message.includes('--force')) {
    // prompt the user or rerun with force
  } else throw err;
}

Prevention

Check for the destination file before invoking install in scripts.
Use --force deliberately only when you intend to overwrite.
Keep workflows under version control so overwrites are recoverable.

When it happens

Trigger: Running the workflow install command (which downloads a workflow into <archonDir>/workflows/<slug>.yaml) when that slug's YAML already exists on disk and the --force flag was not supplied.

Common situations: Re-running an install of a workflow pack that was previously installed; installing a different workflow that happens to use the same slug; leftover files in .archon/workflows from an old checkout or manual copy.

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/fe93d47c51662256. Report an issue: GitHub.