{"record":{"id":"bcc2fbdb1c5a2851","repo":"GitoxideLabs/gitoxide","slug":"could-not-read-local-branch-err","errorCode":null,"errorMessage":"could not read local branch: {err}","messagePattern":"could not read local branch: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gix-tix/src/history.rs","lineNumber":960,"sourceCode":"        .enumerate()\n        .filter(|(_, flags)| flags & (VISIBLE | HIDDEN) == VISIBLE | HIDDEN)\n        .map(|(index, _)| graph.id(CommitIndex(index as u32)))\n        .collect())\n}\n\nfn local_refs_by_target(repo: &gix::Repository) -> Result<HashMap<ObjectId, Vec<BString>>> {\n    let mut out = HashMap::<ObjectId, Vec<BString>>::new();\n    let platform = repo.references().context(\"could not open references\")?;\n    let refs = platform\n        .local_branches()\n        .context(\"could not iterate local branches\")?\n        .peeled()\n        .context(\"could not prepare local branches for peeling\")?;\n    for reference in refs {\n        let reference = match reference {\n            Ok(reference) => reference,\n            Err(err) if is_missing_ref(&*err) => continue,\n            Err(err) => return Err(anyhow::anyhow!(\"could not read local branch: {err}\")),\n        };\n        out.entry(reference.id().detach())\n            .or_default()\n            .push(reference.name().as_bstr().to_owned());\n    }\n    Ok(out)\n}\n\nfn resolve_tracking(repo: &gix::Repository, names: &[BString]) -> Result<Vec<SelectionRef>> {\n    let mut out = Vec::with_capacity(names.len());\n    for full_name in names {\n        let Some(reference) = repo\n            .try_find_reference(full_name.as_bstr())\n            .with_context(|| format!(\"could not read local branch {full_name}\"))?\n        else {\n            continue;\n        };\n        let upstream = reference","sourceCodeStart":942,"sourceCodeEnd":978,"githubUrl":"https://github.com/GitoxideLabs/gitoxide/blob/e73179060badf27222d790981fac3f84c1830a7e/gix-tix/src/history.rs#L942-L978","documentation":"While building the set of local branches for history decoration, tix iterates the repository's branch references. If reading an individual reference fails for a reason other than a transient missing-ref condition (e.g. packed-refs vs loose ref I/O errors, permission problems), the error is wrapped as `could not read local branch: {err}` and returned instead of skipping the branch.","triggerScenarios":"Calling the branch-collection API (the function preparing local branches for peeling, e.g. during history load) when `repo.references()` yields an `Err` on a branch ref that `is_missing_ref` does not classify as ignorable — such as I/O or permission errors reading loose or packed refs.","commonSituations":"Filesystem permission issues on `.git/refs`, partially written or corrupt loose ref files, packed-refs locks, or network/filesystem mount problems on remotes-backed worktrees.","solutions":["Fix filesystem permissions on `.git/refs` and `.git/packed-refs`","Run `git fsck` to find and repair corrupt or dangling ref files","Remove stale lock files under `.git/refs` if a previous operation crashed","Identify the failing branch name from the wrapped error and delete/repair that specific ref"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// check refs are readable before collecting branches\nfn refs_readable(git_dir: &std::path::Path) -> bool {\n    let heads = git_dir.join(\"refs/heads\");\n    match std::fs::read_dir(&heads) {\n        Ok(entries) => entries.all(|e| e.map(|e| e.metadata().map(|m| !m.permissions().readonly()).unwrap_or(true)).unwrap_or(false)),\n        Err(_) => git_dir.join(\"packed-refs\").exists(),\n    }\n}","typeGuard":"fn is_missing_ref_error(err: &dyn std::error::Error) -> bool {\n    err.to_string().to_lowercase().contains(\"not found\")\n}","tryCatchPattern":"match collect_local_branches(&repo) {\n    Ok(branches) => branches,\n    Err(e) if e.to_string().starts_with(\"could not read local branch\") => {\n        eprintln!(\"branch refs unreadable: {e}; repairing refs\");\n        repair_refs(&repo)?;\n        collect_local_branches(&repo)?\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Keep `.git/refs` free of stale `.lock` files","Run `git fsck` periodically on active repositories","Avoid running multiple writers on the same repo from flaky mounts","Fix permission problems on `.git` after user/OS changes"],"tags":["git","refs","io"],"backgroundTag":"git-command-failed","analyzedSha":"e73179060badf27222d790981fac3f84c1830a7e","analyzedAt":"2026-09-08T11:26:50.865Z","contentChangedAt":"2026-09-08T11:26:50.865Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}