coleam00/Archon · error · CodebaseNotFoundError

Codebase ${codebaseId} not found

Error message

Codebase ${codebaseId} not found

What it means

updateCodebase builds a dynamic UPDATE for remote_agent_codebases and throws CodebaseNotFoundError (message 'Codebase ${id} not found') when rowCount is 0, i.e. no row matched the given id. This is the typed signal that the codebase identifier does not exist; callers (e.g. handleUpdateProject) catch it programmatically via its `name`.

Source

Thrown at packages/core/src/db/codebases.ts:195

    values.push(data.repository_url);
  }

  if (data.default_branch !== undefined) {
    updates.push(`default_branch = $${paramIndex++}`);
    values.push(data.default_branch);
  }

  if (updates.length === 0) return;

  updates.push(`updated_at = ${dialect.now()}`);
  values.push(id);

  const result = await pool.query(
    `UPDATE remote_agent_codebases SET ${updates.join(', ')} WHERE id = $${paramIndex}`,
    values
  );
  if ((result.rowCount ?? 0) === 0) {
    throw new CodebaseNotFoundError(id);
  }
}

export async function listCodebases(): Promise<readonly Codebase[]> {
  const result = await pool.query<Codebase>(
    'SELECT * FROM remote_agent_codebases ORDER BY name ASC'
  );
  return result.rows;
}

export async function deleteCodebase(id: string): Promise<void> {
  getLog().debug({ codebaseId: id }, 'db.codebase_delete_cascade_started');
  // First, unlink any sessions referencing this codebase (FK has no cascade)
  await pool.query('UPDATE remote_agent_sessions SET codebase_id = NULL WHERE codebase_id = $1', [
    id,
  ]);
  // Second, unlink any conversations referencing this codebase (FK has no cascade)
  await pool.query(

View on GitHub (pinned to 0773b97458)

Solutions

1. Verify the id: SELECT id, name FROM remote_agent_codebases; compare with the id being updated.
2. Re-create the codebase via the normal create/register flow if it was deleted, then retry the update.
3. Check which database the app is connected to (DSN) — the id may exist in another environment.
4. Clear stale references: update any config/workflow that caches the old codebase id to the current one.
5. Catch CodebaseNotFoundError in calling code and surface a user-facing 'codebase not found' instead of a generic 500.

Example fix

// before
await updateCodebase(id, { name }); // throws if id unknown
// after
try {
  await updateCodebase(id, { name });
} catch (e) {
  if (e instanceof CodebaseNotFoundError) {
    const all = await listCodebases();
    throw new Error(`Codebase ${id} not found. Known: ${all.map(c => c.id).join(', ')}`);
  }
  throw e;
}

const { rows } = await pool.query('SELECT 1 FROM remote_agent_codebases WHERE id = $1', [id]);
if (rows.length === 0) throw new Error(`codebase ${id} does not exist; create it first`);
await updateCodebase(id, updates);

// Error-class narrowing is the idiomatic guard here
function isCodebaseNotFound(e: unknown): e is CodebaseNotFoundError {
  return e instanceof CodebaseNotFoundError;
}

try {
  await updateCodebase(id, updates);
} catch (e) {
  if (isCodebaseNotFound(e)) {
    const known = (await listCodebases()).map(c => c.id);
    throw new Error(`Codebase ${id} not found. Existing ids: ${known.join(', ')}`);
  }
  throw e;
}

When it happens

Trigger: Calling updateCodebase with an id that has no row in remote_agent_codebases — deleted codebase, wrong/typo'd id, or an id from a different environment/database.

Common situations: A codebase was deleted by another operator while a workflow still referenced it; a stale id cached in config; pointing the app at a fresh database that lacks the row; copy-pasting an id from logs of another install.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Conversation not found: ${conversationId}
• Corrupt commands JSON for codebase ${id}: unable to parse st
• Failed to get workflow run status: ${err.message}
• Failed to get active workflow run: ${err.message}
• Failed to get active workflow run by path: ${err.message}

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