{"record":{"id":"bd4711c54fdeb8df","repo":"gitbutlerapp/gitbutler","slug":"no-head-reference-found-for-remote-remote-name","errorCode":null,"errorMessage":"No HEAD reference found for remote {remote_name}","messagePattern":"No HEAD reference found for remote (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/but-action/src/lib.rs","lineNumber":154,"sourceCode":"        }\n    }\n}\n\nfn default_target_setting_if_none(ctx: &Context) -> anyhow::Result<()> {\n    if ctx.project_meta()?.target_ref.is_some() {\n        return Ok(());\n    }\n    // Lets do the equivalent of `git symbolic-ref refs/remotes/origin/HEAD --short` to guess the default target.\n\n    let repo = ctx.repo.get()?;\n    let remote_name = repo\n        .remote_default_name(gix::remote::Direction::Push)\n        .ok_or_else(|| anyhow::anyhow!(\"No push remote set or more than one remote\"))?\n        .to_string();\n\n    let mut head_ref = repo\n        .find_reference(&format!(\"refs/remotes/{remote_name}/HEAD\"))\n        .map_err(|_| anyhow::anyhow!(\"No HEAD reference found for remote {remote_name}\"))?;\n    let target_ref_name = head_ref\n        .target()\n        .try_name()\n        .ok_or_else(|| anyhow::anyhow!(\"Remote HEAD for {remote_name} is not symbolic\"))?\n        .to_owned();\n\n    let head_commit = head_ref.peel_to_commit()?;\n\n    ctx.set_project_meta(ProjectMeta {\n        target_ref: Some(target_ref_name),\n        target_commit_id: Some(head_commit.id),\n        push_remote: None,\n    })?;\n    Ok(())\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, EnumString, Default)]\n#[serde(rename_all = \"camelCase\")]","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/gitbutlerapp/gitbutler/blob/2497b8007aa4a1922dae9a805b32ffe5b5037785/crates/but-action/src/lib.rs#L136-L172","documentation":"While guessing the default target branch, GitButler looks up refs/remotes/<remote>/HEAD (the symref `git remote set-head` creates). If that reference does not exist, find_reference fails and default_target_setting_if_none aborts with this message naming the remote. The remote itself is configured; only its HEAD shortcut is missing.","triggerScenarios":"default_target_setting_if_none on a repo whose push remote has no refs/remotes/<remote>/HEAD: remotes added with `git remote add` but never given a HEAD, shallow or --single-branch clones, repos materialized by scripts that skip the symref.","commonSituations":"git clone --single-branch / --depth clones; tooling and containers that construct remotes manually; older Git clients that did not write remote HEAD; mirror setups.","solutions":["Run git remote set-head <remote> --auto to (re)create refs/remotes/<remote>/HEAD.","If --auto cannot query the remote, set it explicitly: git remote set-head <remote> main.","Or set the target branch directly in GitButler so the guess path never runs.","Verify with git symbolic-ref refs/remotes/<remote>/HEAD."],"exampleFix":"git remote set-head origin --auto\ngit symbolic-ref refs/remotes/origin/HEAD  # should print refs/remotes/origin/<branch>\n# then retry the GitButler action","handlingStrategy":"validation","validationCode":"fn remote_head_exists(repo: &gix::Repository, remote: &str) -> bool {\n    repo.find_reference(&format!(\"refs/remotes/{remote}/HEAD\")).is_ok()\n}\n\n// before the first GitButler action on a repo:\nif !remote_head_exists(repo, &remote_name) {\n    std::process::Command::new(\"git\")\n        .args([\"remote\", \"set-head\", &remote_name, \"--auto\"])\n        .status()?;\n}","typeGuard":null,"tryCatchPattern":"match default_target_setting_if_none(ctx) {\n    Err(err) if err.to_string().contains(\"No HEAD reference found for remote\") => {\n        run_git(&[\"remote\", \"set-head\", &remote, \"--auto\"]); // then retry once\n    }\n    r => r?,\n}","preventionTips":["Run git remote set-head <remote> --auto right after adding any remote.","Avoid --single-branch clones for projects managed by GitButler.","Persist an explicit target_ref at project setup instead of relying on discovery."],"tags":["git-remote","remote-head","target-branch","git-refs"],"backgroundTag":"missing-remote-head-ref","analyzedSha":"2497b8007aa4a1922dae9a805b32ffe5b5037785","analyzedAt":"2026-08-17T00:30:25.648Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}