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

team_worktree_worker_name_required

team_worktree_worker_name_required

Error message

team_worktree_worker_name_required

What it means

Thrown when planning a worker-scoped worktree branch and the worker name is empty after trimming. Worker branches are named `<mode>/<workerName>`, so an empty worker name would produce an invalid/duplicated branch. The library requires an explicit non-empty workerName in worker scope.

Source

Thrown at src/team/worktree.ts:217

  const stderr = (result.stderr || '').trim();
  throw new Error(stderr || `worktree_prune_failed:${worktreePath}`);
}

function resolveBranchName(input: WorktreePlanInput): string | null {
  if (!input.mode.enabled || input.mode.detached) return null;

  if (input.scope === 'launch') {
    return input.mode.name;
  }

  if (input.scope === 'autoresearch') {
    const runTag = sanitizePathToken(input.worktreeTag || 'run');
    return `autoresearch/${sanitizePathToken(input.mode.name)}/${runTag}`;
  }

  const workerName = (input.workerName || '').trim();
  if (!workerName) {
    throw new Error('team_worktree_worker_name_required');
  }

  return `${input.mode.name}/${workerName}`;
}

function resolveWorktreePath(input: WorktreePlanInput, repoRoot: string): string {
  const parent = dirname(repoRoot);
  const bucket = `${basename(repoRoot)}.omx-worktrees`;

  if (input.scope === 'launch') {
    if (!input.mode.enabled || input.mode.detached) {
      return join(parent, bucket, 'launch-detached');
    }
    return join(parent, bucket, `launch-${sanitizePathToken(input.mode.name)}`);
  }

  if (input.scope === 'autoresearch') {
    if (!input.mode.enabled || input.mode.detached) {

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Supply a non-empty workerName whenever scope is 'worker' (e.g. 'researcher', 'coder')
2. Default workerName from your own config before calling the planner if the field is optional in your system
3. Validate workerName early in your CLI/config layer and fail with a helpful message
4. If no per-worker identity is needed, use launch scope instead, which derives a name from mode and run tag

Example fix

// before
planWorktreeTarget({ scope: 'worker', mode: { enabled: true, name: 'bench' }, workerName: workerName }); // undefined

// after
if (scope === 'worker' && !(workerName ?? '').trim()) {
  throw new Error('Missing --worker name for worker-scoped worktree');
}
planWorktreeTarget({ scope: 'worker', mode: { enabled: true, name: 'bench' }, workerName: workerName!.trim() });

function hasWorkerName(input: { workerName?: string | null }): boolean {
  return !!(input.workerName ?? '').trim();
}

function isNonEmptyWorkerName(s: unknown): s is string {
  return typeof s === 'string' && s.trim().length > 0;
}

catch (e) { if (e instanceof Error && e.message === 'team_worktree_worker_name_required') { /* prompt for worker name or default it */ } else throw e; }

When it happens

Trigger: Calling planWorktreeTarget with scope 'worker' (mode enabled, not detached) and workerName undefined, null, or whitespace-only.

Common situations: Passing an options object built from CLI args where --worker was omitted; workerName sourced from an env var that's unset; trimming logic upstream that reduces the name to ''; misconfigured team definition missing the worker name field.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• scale_down_cleanup_debt_invalid_worktree_metadata:${worker.n
• scale_down_cleanup_debt_invalid_worktree_target:${worker.nam
• `target` is required
• worktreeName must be a relative safe worktree name
• answers[${entry.index}].answer.other_text must be a non-empt

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