Cannot dispatch workflow "${workflow.name}": codebase ${ctx.

Error message

Cannot dispatch workflow "${workflow.name}": codebase ${ctx.codebaseId} not found

What it means

dispatchBackgroundWorkflowOwned validates that the ctx.codebaseId referenced by a dispatch actually exists before wiring worktree isolation and the base branch. If getCodebase returns null, it throws immediately so the workflow is not dispatched against an unknown codebase. This is a fail-fast guard for a dangling codebase reference.

Source

Thrown at packages/core/src/orchestrator/orchestrator.ts:402

  await db.updateConversation(workerConv.id, {
    cwd: ctx.cwd,
    codebase_id: ctx.codebaseId ?? null,
    hidden: true,
  });

  // 3. Resolve isolation for this worker. Unless the workflow explicitly opts out of
  // worktrees, each background workflow gets its own worktree — and isolation failure
  // is then fatal (never fall back to running in a shared/parent worktree).
  let workerCwd: string;
  let codebaseBaseBranch: string | undefined;
  // Per-child isolation resolver (#2121 slice 2, PR-A): a `workflow:` node with
  // `isolation: 'worktree'` gets its own worktree per child. Built for git-repo
  // codebases only; undefined otherwise → the engine fails such a node fast.
  let resolveChildIsolation: ReturnType<typeof createChildWorktreeResolver> | undefined;
  if (ctx.codebaseId) {
    const codebase = await getCodebase(ctx.codebaseId);
    if (!codebase) {
      throw new Error(
        `Cannot dispatch workflow "${workflow.name}": codebase ${ctx.codebaseId} not found`
      );
    }
    codebaseBaseBranch = codebase.default_branch?.trim() || undefined;
    if (codebase.kind !== 'folder') {
      resolveChildIsolation = createChildWorktreeResolver({
        codebaseId: codebase.id,
        codebaseName: codebase.name,
        canonicalRepoPath: codebase.default_cwd,
        baseBranch: codebaseBaseBranch,
        createdByPlatform: ctx.platform.getPlatformType(),
        createdByUserId: ctx.userId,
      });
    }
    if (workflow.worktree?.enabled === false) {
      // Respect an explicit worktree opt-out: skip isolation and run in the parent's cwd.
      getLog().info(
        {

View on GitHub (pinned to 0773b97458)

Solutions

Run the codebase list/registration command to see valid ids and register the missing codebase.
Correct the codebaseId in the dispatch context to a registered id.
Re-create the codebase registration if it was deleted and the id must stay stable.
Check you are pointed at the correct Archon database/install where the codebase exists.

Example fix

// before
await dispatchBackgroundWorkflow({ ctx: { codebaseId: 'cb_123' }, ... });
// after: verify registration first
const cb = await getCodebase('cb_123');
if (!cb) throw new Error('Register codebase cb_123 before dispatching');
await dispatchBackgroundWorkflow({ ctx: { codebaseId: 'cb_123' }, ... });

Defensive patterns

Strategy: validation

Validate before calling

const cb = await getCodebase(ctx.codebaseId);
if (!cb) throw new Error(`codebase ${ctx.codebaseId} is not registered; register it before dispatch`);

Try / catch

try {
  await dispatchBackgroundWorkflow(req);
} catch (e) {
  if (e.message.includes('codebase') && e.message.includes('not found')) {
    console.error('Register the codebase or fix codebaseId');
  } else throw e;
}

Prevention

Fetch codebase ids from the registry at dispatch time instead of hardcoding them.
Delete or update schedulers/automations when a codebase is unregistered.
Avoid copying codebase ids between installs or databases.

When it happens

Trigger: Calling dispatchBackgroundWorkflow with ctx.codebaseId set to an id that is not registered (deleted registration, typo, stale id from another install/database, or wrong database attached).

Common situations: A codebase was unregistered while a scheduler/cron still references its id; copying run configs between machines or databases; hand-edited workflow payloads; a stale UI session holding a deleted codebase id.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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