{"record":{"id":"0b6e5998b4bbdb63","repo":"coleam00/Archon","slug":"cannot-detect-default-branch-for-repopath-re","errorCode":null,"errorMessage":"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.","messagePattern":"Cannot detect default branch for (.+?): (.+?)/HEAD is not set\\. Pass --base, set worktree\\.baseBranch in \\.archon/config\\.yaml, or set the codebase default_branch field\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/git/src/branch.ts","lineNumber":55,"sourceCode":"  try {\n    const { stdout } = await execFileAsync(\n      'git',\n      ['-C', repoPath, 'symbolic-ref', `refs/remotes/${remote}/HEAD`, '--short'],\n      { timeout: 10000 }\n    );\n    // stdout is like \"origin/main\" - extract just the branch name\n    return toBranchName(stdout.trim().replace(`${remote}/`, ''));\n  } catch (error) {\n    const err = error as Error & { stderr?: string };\n    const errorText = `${err.message} ${err.stderr ?? ''}`;\n\n    // Expected: symbolic-ref not set (fresh clone without `git remote set-head`).\n    // Cannot detect the default branch — surface a config-driven fix instead of\n    // guessing. See #2471.\n    if (errorText.includes('not a symbolic ref')) {\n      getLog().warn({ repoPath, remote }, 'default_branch_detection_failed');\n      throw new Error(\n        `Cannot detect default branch for ${repoPath}: ${remote}/HEAD is not set. ` +\n          'Pass --base, set worktree.baseBranch in .archon/config.yaml, ' +\n          'or set the codebase default_branch field.'\n      );\n    }\n\n    // Unexpected error (permission denied, git corruption, etc.) - surface it\n    getLog().error(\n      { repoPath, remote, err, stderr: err.stderr },\n      'default_branch_symbolic_ref_failed'\n    );\n    throw new Error(`Failed to get default branch for ${repoPath}: ${err.message}`);\n  }\n}\n\n/**\n * Count commits that would become unreachable if a local branch and its remote\n * counterpart were deleted.\n *","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/git/src/branch.ts#L37-L73","documentation":"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).","triggerScenarios":"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.","commonSituations":"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`.","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."],"exampleFix":"// before\n$ git symbolic-ref refs/remotes/origin/HEAD\nerror: ref refs/remotes/origin/HEAD is not a symbolic ref\n// after\n$ git remote set-head origin --auto\norigin/HEAD set to main","handlingStrategy":"validation","validationCode":"import { execSync } from 'node:child_process';\nfunction remoteHeadSet(repoPath: string, remote = 'origin'): boolean {\n  try {\n    execSync(`git -C ${repoPath} symbolic-ref refs/remotes/${remote}/HEAD`, { stdio: 'pipe' });\n    return true;\n  } catch { return false; }\n}\nif (!remoteHeadSet(repoPath)) console.error('Set --base or worktree.baseBranch before proceeding');","typeGuard":null,"tryCatchPattern":"try {\n  const branch = await getDefaultBranch(repoPath);\n} catch (e) {\n  if ((e as Error).message.includes('Cannot detect default branch')) {\n    const branch = config.worktree?.baseBranch ?? await promptForBase();\n  } else throw e;\n}","preventionTips":["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."],"tags":["git","worktree","default-branch"],"backgroundTag":"remote-head-not-set","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}