What causes "caller knows there is a common iter" in GitoxideLabs/gitoxide?

Check that your repository/worktree layout is detected correctly (presence of `commondir` file, linked worktrees)

caller knows there is a common iter

Error message

caller knows there is a common iter

What it means

The overlay store iterator merges the git-dir and common-dir loose views plus the packed-refs view. `loose_iter` picks the inner iterator for the given `IterKind`; `IterKind::Common` requires `iter_common_dir` to be `Some`, which is guaranteed by construction whenever the common kind is produced. The `expect` fails only if the overlay iterator was built without a common-dir iterator while still yielding `Common` kinds.

Solutions

Check that your repository/worktree layout is detected correctly (presence of `commondir` file, linked worktrees)
Try reproducing with plain `git for-each-ref` to see if the repository layout itself is unusual
If it reproduces on a standard repository, report a gix-ref bug with the repo layout
Work around by iterating `store.iter()` results rather than relying on the mixed overlay enumeration, or upgrade gix-ref

Defensive patterns

Strategy: fallback

Try / catch

// Panics can't be caught idiomatically; wrap iteration in catch_unwind if resilience is required
let refs = std::panic::catch_unwind(|| store.iter().collect::<Vec<_>>()).map_err(|_| "iteration panicked");

Prevention

Use standard worktree layouts (normal `.git` + `worktrees/`) where common-dir detection is well tested
Test iteration on the actual repository layout before relying on it in production
Upgrade gix-ref when this panic appears; it signals a library bug
Compare behavior with `git for-each-ref` to confirm layout oddities

When it happens

Trigger: Iterating references of an overlay (`StoreIter`) where the internal kind tag says `Common` but no common-dir iterator was initialized — an internal inconsistency, e.g. after a misuse of internal APIs or a gix-ref bug.

Common situations: Not reachable through public APIs on a correctly detected repository layout; if seen, it usually indicates a bug in common-dir detection (e.g. worktree setups where `commondir` resolution differs from what the iterator assumed) or custom store construction.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at gix-ref/src/store/file/overlay_iter.rs:63

impl<'p> LooseThenPacked<'p, '_> {
    fn strip_namespace(&self, mut r: Reference) -> Reference {
        if let Some(namespace) = &self.namespace {
            r.strip_namespace(namespace);
        }
        r
    }

    fn loose_iter(&mut self, kind: IterKind) -> &mut Peekable<SortedLoosePaths> {
        match kind {
            IterKind::GitAndConsumeCommon => {
                drop(self.iter_common_dir.as_mut().map(Iterator::next));
                &mut self.iter_git_dir
            }
            IterKind::Git => &mut self.iter_git_dir,
            IterKind::Common => self
                .iter_common_dir
                .as_mut()
                .expect("caller knows there is a common iter"),
        }
    }

    fn convert_packed(
        &mut self,
        packed: Result<packed::Reference<'p>, packed::iter::Error>,
    ) -> Result<Reference, Error> {
        packed
            .map(Into::into)
            .map(|r| self.strip_namespace(r))
            .map_err(|err| match err {
                packed::iter::Error::Reference {
                    invalid_line,
                    line_number,
                } => Error::PackedReference {
                    invalid_line,
                    line_number,
                },

View on GitHub (pinned to e73179060b)