What causes "failed to initialize team config" in Yeachan-Heo/oh-my-codex?

Clean stale team state (the detectAndCleanStaleTeam path or manual removal of the team state root) and retry

Yeachan-Heo/oh-my-codex · critical · Error

failed to initialize team config

Error message

failed to initialize team config

What it means

Thrown when the call to initialize the team configuration (with identity scope, worktree mode, etc.) returns a falsy config. This is an internal invariant failure: the config factory (persisted under key 'default') failed to produce a configuration object, so startup cannot continue.

Source

Thrown at src/team/runtime.ts:3603

      {
        ...launchEnv,
        OMX_SESSION_ID: leaderSessionId,
        OMX_TEAM_DISPLAY_MODE: displayMode,
        OMX_TEAM_WORKER_LAUNCH_MODE: workerLaunchMode,
      },
      {
        leader_cwd: leaderCwd,
        team_state_root: teamStateRoot,
        workspace_mode: workspaceMode,
        display_name: displayName,
        requested_name: displayName,
        identity_source: identityScope.source,
        worktree_mode: effectiveWorktreeMode,
      },
      'default',
    );
    if (!config) {
      throw new Error('failed to initialize team config');
    }
    config.leader_cwd = leaderCwd;
    config.team_state_root = teamStateRoot;
    config.workspace_mode = workspaceMode;
    config.display_name = displayName;
    config.requested_name = displayName;
    config.identity_source = identityScope.source;
    config.worktree_mode = effectiveWorktreeMode;
    await writePersistedApprovedTeamExecutionBinding(
      sanitized,
      leaderCwd,
      approvedExecution,
      teamStateRoot,
    );
    await writePersistedTeamUltragoalContext(
      sanitized,
      leaderCwd,
      ultragoalContext,

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Clean stale team state (the detectAndCleanStaleTeam path or manual removal of the team state root) and retry
Check write permissions and disk space for the leader cwd / team state root directory
Inspect logs from the config initialization call to see why it returned null
Upgrade/downgrade to a matching version if the config schema changed

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify the team state root is writable before starting
import { access, constants } from 'node:fs/promises';
await access(teamStateRoot, constants.W_OK);

Try / catch

try {
  await startTeam(opts);
} catch (e) {
  if (e instanceof Error && e.message === 'failed to initialize team config') {
    // clean state root and retry once
    await cleanupTeamState(leaderCwd);
    return startTeam(opts);
  }
  throw e;
}

Prevention

Keep the team state root clean; remove stale state before starting
Ensure write permissions and disk space on the config directory
Run only one leader at a time per team name

When it happens

Trigger: Calling team startup when the underlying config initialization (createTeamConfig with the sanitized name and 'default' profile) returns null/undefined — typically a corrupted or unreadable team config store, invalid identity source resolution, or a write failure in the config directory.

Common situations: Corrupted team state files in the repo's team state root; permission errors on the config directory; disk full; partially cleaned-up stale team state; version change altering the config schema making deserialization fail.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/c5812283d6cb5b1c. Report an issue: GitHub.