GitoxideLabs/gitoxide · error

could not inspect a reference before editing

Error message

could not inspect a reference before editing: {err}

What it means

Before performing an edit, tix scans all references to collect tags, remote branches, and undo-queue refs that need updating. Most per-reference errors are tolerated (missing refs are skipped), but any other failure to inspect a reference aborts the whole edit, because proceeding could rewrite history while missing refs that point into it.

Solutions

1. Run `git fsck` and `git pack-refs --all` to detect and repair corrupted or malformed references, then retry.
2. Check read permissions on `.git/refs`, `packed-refs`, and any worktree ref directories; fix ownership/permissions.
3. Remove stale ref lock files (`.git/refs/**.lock`) left by crashed processes.
4. If a specific ref is irrecoverable, delete and recreate it before running the edit.

Example fix

// before: corrupted packed-refs entry aborts the scan
// error: could not inspect a reference before editing: ...

// after: repair refs first
git fsck --no-progress
git pack-refs --all --prune

// Shell: pre-flight ref health check before editing
git fsck --no-progress || exit 1
test -r .git/packed-refs || true

// Rust
match plan_edits(repo) {
    Err(e) if e.to_string().starts_with("could not inspect a reference") => {
        eprintln!("repair refs (git fsck / pack-refs) and retry");
    }
    other => other?,
}

When it happens

Trigger: Iterating `repo.references()?.all()?` when the underlying ref-backend iterator yields an `Err` that is not a missing-ref: corrupted or unreadable loose/packed refs, permission problems on `.git/refs`, or a storage-backend error.

Common situations: A damaged repository (truncated packed-refs, stale lock files, partially deleted refs); refs files unreadable due to file permissions or sandboxing; worktrees with unusual ref backends.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• could not inspect a reference before rebasing
• could not read review reference
• a symbolic reference chain contains a cycle
• could not read local branch
• could not read reference

AI-assisted analysis of GitoxideLabs/gitoxide@e73179060b (2026-09-08). Data as JSON: /api/errors/e7e086f96dad1a9f. Report an issue: GitHub.

Appendix: source

Thrown at gix-tix/src/edit/rebase.rs:411

    committer: gix::actor::Signature,
    expected_refs: Option<Vec<ExpectedRef>>,
    checkout_reference: Option<gix::refs::FullName>,
    checkout_after_finish: bool,
    pins: Vec<ObjectId>,
    delete_refs: Vec<(gix::refs::FullName, Target)>,
    enrichment: Option<(ObjectId, BString)>,
}

pub(crate) fn capture_refs(repo: &gix::Repository, scope: &[ObjectId], tips: &[ObjectId]) -> Result<Vec<ExpectedRef>> {
    let scope: HashSet<_> = scope.iter().copied().collect();
    let tips: HashSet<_> = tips.iter().copied().collect();
    let mut out = Vec::new();
    let mut seen = HashSet::new();
    for reference in repo.references()?.all()? {
        let reference = match reference {
            Ok(reference) => reference,
            Err(err) if is_missing_ref(&*err) => continue,
            Err(err) => anyhow::bail!("could not inspect a reference before editing: {err}"),
        };
        if matches!(
            reference.name().category(),
            Some(Category::Tag | Category::RemoteBranch)
        ) || super::undo::is_queue_ref(reference.name().as_bstr())
        {
            continue;
        }
        let Some(old) = reference.try_id().map(gix::Id::detach) else {
            continue;
        };
        if scope.contains(&old) && seen.insert(reference.name().to_owned()) {
            out.push(ExpectedRef {
                name: reference.name().to_owned(),
                old: Some(old),
                target: old,
                new: Some(old),
                follows_tip: tips.contains(&old),

View on GitHub (pinned to e73179060b)