Container env '${envId}' not found (its tracking row is gone

Error message

Container env '${envId}' not found (its tracking row is gone).

What it means

loadMetadata looks up a container environment's tracking row in the isolation store by id. When the row is absent the env's persisted state (metadata) cannot be recovered, so the library throws instead of fabricating a partial metadata object.

Source

Thrown at packages/isolation/src/backends/container.ts:472

  /**
   * Discard the overlay diff (write-back rejected). The live root is never touched;
   * the volume is reclaimed by the caller's subsequent `destroy`. A no-op beyond a
   * breadcrumb — the discard IS "do nothing to the live root, then destroy".
   */
  async discardChanges(envId: string): Promise<void> {
    log.info({ envId }, 'isolation.container_changes_discarded');
  }

  /**
   * Load a container env's persisted metadata, or throw if the row is gone. The
   * store normalizes `metadata` to a parsed object on every dialect (SQLite returns
   * it as a JSON string otherwise), so this reads it directly.
   */
  private async loadMetadata(envId: string): Promise<Partial<ContainerEnvMetadata>> {
    const row = await this.store.getById(envId);
    if (!row) {
      throw new Error(`Container env '${envId}' not found (its tracking row is gone).`);
    }
    return row.metadata as Partial<ContainerEnvMetadata>;
  }

  private preparedEnvFor(
    containerId: string,
    cwd: string,
    envId: string,
    overlayMode: OverlayMode
  ): PreparedEnv {
    return { cwd, execContext: { kind: 'container', containerId }, envId, overlayMode };
  }

  /**
   * Container presence as three outcomes: `running`, `stopped` (exists but not
   * running), or `missing` (no such container). Distinct from {@link containerState}
   * which folds "missing" and "inspect blip" into `unknown` — resume MUST tell
   * "gone" (→ recreate over the volume) apart from "stopped" (→ start).

View on GitHub (pinned to 0773b97458)

Solutions

Verify the envId exists by listing current container envs before reading metadata
Re-create or resume the environment if the id is stale
Check whether cleanup/pruning removed the tracking row and restore the database backup if needed

Example fix

// before
const metadata = await backend.meta('env-abc123');
// after
const envs = await backend.listEnvs?.() ?? [];
if (!envs.some(e => e.id === 'env-abc123')) throw new Error('env not found');
const metadata = await backend.meta('env-abc123');

Defensive patterns

Strategy: validation

Validate before calling

const exists = await store.getById(envId);
if (!exists) throw new Error(`Unknown env id: ${envId}`);
const metadata = await backend.meta(envId);

Type guard

function isEnvRow(row: unknown): row is { id: string; metadata: Record<string, unknown> } {
  return typeof row === 'object' && row !== null && 'id' in row && 'metadata' in row;
}

Try / catch

try {
  return await backend.meta(envId);
} catch (err) {
  if (String(err).includes('not found (its tracking row is gone)')) {
    return null; // treat as absent env
  }
  throw err;
}

Prevention

List available env ids before dereferencing metadata
Avoid holding env ids across cleanups or store resets
Handle concurrent cleanup races by re-listing after a not-found

When it happens

Trigger: Calling meta() (directly or indirectly) with an envId that no longer exists in the store — e.g. the row was pruned by cleanup, the env was removed concurrently, or the id is stale/typo'd.

Common situations: Calling meta() for an env that was already removed by another process; a deleted database or schema reset wiping rows; passing an id from a previous run after re-initializing the store.

Related errors

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