Cannot detect default branch for ${repoPath}: ${remote}/HEAD

Error message

Cannot detect default branch for ${repoPath}: ${remote}/HEAD is not set. Pass --base, set worktree.baseBranch in .archon/config.yaml, or set the codebase default_branch field.

What it means

getDefaultBranch throws this when it cannot determine a repository's default branch because `<remote>/HEAD` is not a symbolic ref — typical of a fresh clone where `git remote set-head` was never run. Instead of guessing, it surfaces a config-driven fix and logs default_branch_detection_failed (issue #2471).

Source

Thrown at packages/git/src/branch.ts:55

  try {
    const { stdout } = await execFileAsync(
      'git',
      ['-C', repoPath, 'symbolic-ref', `refs/remotes/${remote}/HEAD`, '--short'],
      { timeout: 10000 }
    );
    // stdout is like "origin/main" - extract just the branch name
    return toBranchName(stdout.trim().replace(`${remote}/`, ''));
  } catch (error) {
    const err = error as Error & { stderr?: string };
    const errorText = `${err.message} ${err.stderr ?? ''}`;

    // Expected: symbolic-ref not set (fresh clone without `git remote set-head`).
    // Cannot detect the default branch — surface a config-driven fix instead of
    // guessing. See #2471.
    if (errorText.includes('not a symbolic ref')) {
      getLog().warn({ repoPath, remote }, 'default_branch_detection_failed');
      throw new Error(
        `Cannot detect default branch for ${repoPath}: ${remote}/HEAD is not set. ` +
          'Pass --base, set worktree.baseBranch in .archon/config.yaml, ' +
          'or set the codebase default_branch field.'
      );
    }

    // Unexpected error (permission denied, git corruption, etc.) - surface it
    getLog().error(
      { repoPath, remote, err, stderr: err.stderr },
      'default_branch_symbolic_ref_failed'
    );
    throw new Error(`Failed to get default branch for ${repoPath}: ${err.message}`);
  }
}

/**
 * Count commits that would become unreachable if a local branch and its remote
 * counterpart were deleted.
 *

View on GitHub (pinned to 0773b97458)

Solutions

Pass the branch explicitly for this invocation: `--base <branch>` on the workflow/worktree command.
Set `worktree.baseBranch` in the project's .archon/config.yaml to make it persistent.
Set the `default_branch` field on the codebase record.
Alternatively fix the repo itself: `git remote set-head origin --auto` (needs network) or `git remote set-head origin main`.
Re-run the command after the remote HEAD is resolvable.

Example fix

// before
$ git symbolic-ref refs/remotes/origin/HEAD
error: ref refs/remotes/origin/HEAD is not a symbolic ref
// after
$ git remote set-head origin --auto
origin/HEAD set to main

Defensive patterns

Strategy: validation

Validate before calling

import { execSync } from 'node:child_process';
function remoteHeadSet(repoPath: string, remote = 'origin'): boolean {
  try {
    execSync(`git -C ${repoPath} symbolic-ref refs/remotes/${remote}/HEAD`, { stdio: 'pipe' });
    return true;
  } catch { return false; }
}
if (!remoteHeadSet(repoPath)) console.error('Set --base or worktree.baseBranch before proceeding');

Try / catch

try {
  const branch = await getDefaultBranch(repoPath);
} catch (e) {
  if ((e as Error).message.includes('Cannot detect default branch')) {
    const branch = config.worktree?.baseBranch ?? await promptForBase();
  } else throw e;
}

Prevention

Run `git remote set-head origin --auto` once after cloning any repo used with worktree workflows.
Always configure worktree.baseBranch in .archon/config.yaml for CI/shallow clones.
Set the codebase default_branch field when registering projects.
In shallow (--depth 1) checkouts, never rely on automatic default-branch detection.

When it happens

Trigger: Any caller (baseBranch, branch, branchToSync, executeWorkflow) resolving the default branch via `git symbolic-ref refs/remotes/<remote>/HEAD` on a repo whose remote HEAD was never set, or after a shallow/partial clone that omitted it.

Common situations: Newly cloned repositories (git clone sets remote HEAD only in recent git versions / fetch configurations); bare mirrors; repos created by copying a working tree without remote refs; CI checkouts using `--depth 1`.

Related errors

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