Ambiguous project name '${name}'. Did you mean:\n${candidate

Error message

Ambiguous project name '${name}'. Did you mean:\n${candidates}

What it means

resolveCodebaseName's checkTier throws when a project name supplied by the user matches more than one configured project/codebase entry. The engine refuses to guess and lists the matching candidate names so the caller can disambiguate.

Source

Thrown at packages/core/src/orchestrator/orchestrator-agent.ts:506

 *
 * Mirrors `resolveWorkflowName` (packages/workflows/src/router.ts) but uses
 * prefix instead of suffix for tier 3 — project names don't follow the
 * `archon-X` suffix convention workflows use.
 */
function resolveCodebaseName(name: string, codebases: readonly Codebase[]): Codebase | undefined {
  const exact = codebases.find(c => c.name === name);
  if (exact) return exact;

  const lowerName = name.toLowerCase();

  function checkTier(matches: readonly Codebase[], logEvent: string): Codebase | undefined {
    if (matches.length === 1) {
      getLog().debug({ requested: name, matched: matches[0].name }, logEvent);
      return matches[0];
    }
    if (matches.length > 1) {
      const candidates = matches.map(c => `  - ${c.name}`).join('\n');
      throw new Error(`Ambiguous project name '${name}'. Did you mean:\n${candidates}`);
    }
    return undefined;
  }

  return (
    checkTier(
      codebases.filter(c => c.name.toLowerCase() === lowerName),
      'project.set_resolve_case_insensitive_match'
    ) ??
    checkTier(
      codebases.filter(c => c.name.toLowerCase().startsWith(lowerName)),
      'project.set_resolve_prefix_match'
    ) ??
    checkTier(
      codebases.filter(c => c.name.toLowerCase().includes(lowerName)),
      'project.set_resolve_substring_match'
    )
  );

View on GitHub (pinned to 0773b97458)

Solutions

Rename one of the colliding project entries so names are unique.
Use the fully qualified or more specific name of the intended project.
Review the candidates listed in the error and update the calling config/command to use one exactly.

Example fix

// before (archon config)
projects: [{ name: 'api', path: '~/frontend-api' }, { name: 'api', path: '~/backend-api' }]
// after
projects: [{ name: 'frontend-api', path: '~/frontend-api' }, { name: 'backend-api', path: '~/backend-api' }]

Defensive patterns

Strategy: validation

Validate before calling

const projects = listProjects();
const matches = projects.filter(p => nameMatches(p.name, requested));
if (matches.length > 1) throw new Error(`Ambiguous '${requested}': ${matches.map(m => m.name).join(', ')}`);

Try / catch

try {
  await startRun({ codebase: requested });
} catch (e) {
  if (e.message.startsWith('Ambiguous project name')) {
    const candidates = e.message.split('\n').slice(1);
    promptUserToChoose(candidates);
  } else throw e;
}

Prevention

Keep project names unique across all config tiers; enforce uniqueness at config load.
Avoid multiple projects sharing a directory basename.
Surface the candidate list to users in interactive flows instead of free-text names.

When it happens

Trigger: Configuring two projects (e.g. in different name tiers) whose names both match the requested name — exact duplicates or overlapping matches — then starting a run or conversation that references the ambiguous name.

Common situations: Two client repos with the same basename in different directories ('api' for both frontend-api and backend-api); a project renamed so an old alias now collides with a new entry; case-insensitive matching colliding 'MyApp'/'myapp'.

Related errors

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