{"record":{"id":"bd4711c54fdeb8df","repo":"gitbutlerapp/gitbutler","slug":"no-head-reference-found-for-remote-remote-name-bd4711","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/58e5313667b857ef39a730e380af31816a7b1768/crates/but-action/src/lib.rs#L136-L172","documentation":"After determining the default push remote, default_target_setting_if_none looks up refs/remotes/<remote>/HEAD, which encodes the remote's default branch. If that symbolic reference does not exist in the local repo, this error is thrown, because without it GitButler cannot guess which branch should be the workspace target.","triggerScenarios":"default_target_setting_if_none calls repo.find_reference(\"refs/remotes/{remote_name}/HEAD\") and the ref is absent — the clone was made with a git version/setting that skips remote HEAD, or no fetch has populated remote-tracking refs yet.","commonSituations":"Shallow or partial clones missing remote-tracking refs; repos cloned with remote.origin.fetch configured narrowly (single-branch clone) so refs/remotes/origin/HEAD was never created; a bare/mirrored setup copied without the HEAD symref.","solutions":["Recreate the remote HEAD: `git remote set-head origin --auto` (queries the remote for its default branch), then retry.","Or set it manually: `git remote set-head origin main` (or the actual default branch).","Run a full fetch (`git fetch origin`) to populate remote-tracking refs if the clone is single-branch.","Configure the GitButler target branch explicitly to skip the guesswork."],"exampleFix":"// before\n$ git branch -r\n  origin/main   # but no origin/HEAD\n\n// after\n$ git remote set-head origin --auto\n$ retry operation","handlingStrategy":"validation","validationCode":"if repo.find_reference(\"refs/remotes/origin/HEAD\").is_err() {\n    // repair before calling the API:\n    // git remote set-head origin --auto\n}","typeGuard":null,"tryCatchPattern":"match default_target_setting_if_none(ctx) {\n    Err(e) if e.to_string().contains(\"No HEAD reference found\") => {\n        // run `git remote set-head <remote> --auto`, then retry\n    }\n    other => other?,\n}","preventionTips":["Run `git remote set-head <remote> --auto` after cloning, especially for single-branch or shallow clones.","Avoid single-branch fetch configs that skip refs/remotes/<remote>/HEAD.","Set the GitButler target explicitly in projects whose remote HEAD is unreliable."],"tags":["git-refs","remote-head","target-branch","clone-state"],"backgroundTag":"resource-not-found","analyzedSha":"58e5313667b857ef39a730e380af31816a7b1768","analyzedAt":"2026-09-18T06:50:32.052Z","contentChangedAt":"2026-09-18T06:50:32.052Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}