coleam00/Archon · error · Error

Cannot resolve run id prefix '${runId}' outside a registered

Error message

Cannot resolve run id prefix '${runId}' outside a registered project.

What it means

Variant of prefix resolution failure: a cwd was supplied (or implied) but findCodebaseForCheckoutPath returned no codebase — the directory is not a registered project — so the prefix cannot be scoped. Thrown only when requirePrefixMatch is set; otherwise the raw prefix is returned.

Source

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

 */
async function resolveRunIdArg(
  runId: string,
  cwd?: string,
  requirePrefixMatch = false,
  codebaseId?: string
): Promise<string> {
  if (FULL_RUN_ID_RE.test(runId)) return runId;
  if (cwd === undefined && codebaseId === undefined) {
    if (requirePrefixMatch) {
      throw new Error(`Cannot resolve run id prefix '${runId}' without a project directory.`);
    }
    return runId;
  }
  const resolvedCodebaseId =
    codebaseId ?? (cwd === undefined ? undefined : (await findCodebaseForCheckoutPath(cwd))?.id);
  if (!resolvedCodebaseId) {
    if (requirePrefixMatch) {
      throw new Error(`Cannot resolve run id prefix '${runId}' outside a registered project.`);
    }
    return runId;
  }
  const matches = await workflowDb.findWorkflowRunsByIdPrefix(runId, resolvedCodebaseId);
  if (matches.length > 1) {
    const candidates = matches.map(match => `  ${match.id}`).join('\n');
    throw new Error(
      `Run id '${runId}' matches more than one run in this project:\n${candidates}\nUse more characters or the full id.`
    );
  }
  if (matches.length === 0) {
    if (requirePrefixMatch) {
      throw new Error(`No workflow run matches prefix '${runId}' in this project.`);
    }
    return runId;
  }
  return matches[0].id;
}

View on GitHub (pinned to 0773b97458)

Solutions

Register the current checkout: `archon project register` (from the checkout root).
Use the full run id instead of a prefix.
Verify the registration points at this exact path — registration is by checkout path, so a moved directory needs re-registration.

Example fix

// before
archon workflow resume ab12   # unregistered dir
// after
archon project register && archon workflow resume ab12

Defensive patterns

Strategy: validation

Validate before calling

const reg = await findCodebaseForCheckoutPath(cwd).catch(() => null); if (!reg && !isFullRunId(id)) throw new Error('register this checkout or use the full run id');

Try / catch

try { await resume(prefix); } catch (e) { if (String(e.message).includes('outside a registered project')) { execSync('archon project register'); await resume(prefix); } }

Prevention

Register every checkout (including worktrees) right after cloning.
Detect moved checkouts: if the directory path changed, re-register before using prefix ids.
Keep a mapping of run id -> project so scripts can cd to the right checkout first.

When it happens

Trigger: `workflow get/resume/approve <short-prefix>` executed inside a directory that has never been registered with Archon (or whose registration row was deleted), with requirePrefixMatch enabled.

Common situations: Fresh clones without re-registration, moved/renamed checkout directories, deleted codebase rows, running in a worktree that was never registered.

Related errors

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