GitoxideLabs/gitoxide · info

one of our bases contains the path

Error message

one of our bases contains the path

What it means

When converting a loose reference file into a `Reference` fails during overlay iteration, the error path computes a `relative_path` by stripping the git-dir or common-dir prefix from the file path. The `expect("one of our bases contains the path")` asserts the ref file being iterated always lives under one of those two roots. A panic means iteration produced a path outside both bases.

Solutions

1. Inspect the loose ref files in `.git/refs` and `$GIT_COMMON_DIR/refs` for corruption or odd permissions
2. Check for `GIT_COMMON_DIR` env overrides or symlinked git-dir layouts that confuse root detection
3. Fix or remove the corrupt ref file; run `git fsck` for reference-level validation
4. If paths are all normal and it still panics, file a gix-ref bug with the repository layout

// Ensure loose ref files live under git-dir or common-dir before custom iteration
assert!(refpath.starts_with(git_dir) || refpath.starts_with(common_dir));

// Panic path; run fsck and repair instead of attempting recovery
// git fsck --strict && rm/fix corrupt refs, then re-run iteration

When it happens

Trigger: Iterating references where a loose ref file path (`refpath`) is neither under the git-dir nor the common-dir — an internal inconsistency in root setup, or a failed `ReferenceCreation` error path caused by an unreadable/corrupt loose ref file whose path was mis-derived.

Common situations: Seen (if at all) around odd repository setups: symlinked git-dirs, `GIT_COMMON_DIR` manipulation, or manual edits to `.git` layout. The underlying `ReferenceCreation` failure (corrupt ref file) is the real trigger; the panic is a secondary bug.

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

• prior peek
• BUG: packed refs cannot contain symbolic refs, catch that…
• BUG: pack now is smaller than all previously seen entries
• in-bound distance of deltas
• name conversion infallible

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

Appendix: source

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

        let git_dir = self.git_dir;
        let common_dir = self.common_dir;
        let (refpath, name) = res.map_err(Error::Traversal)?;
        std::fs::File::open(&refpath)
            .and_then(|mut f| {
                buf.clear();
                f.read_to_end(buf)
            })
            .map_err(|err| Error::ReadFileContents {
                source: err,
                path: refpath.to_owned(),
            })?;
        loose::Reference::try_from_path(name, buf, self.object_hash)
            .map_err(|err| {
                let relative_path = refpath
                    .strip_prefix(git_dir)
                    .ok()
                    .or_else(|| common_dir.and_then(|common_dir| refpath.strip_prefix(common_dir).ok()))
                    .expect("one of our bases contains the path");
                Error::ReferenceCreation {
                    source: err,
                    relative_path: relative_path.into(),
                }
            })
            .map(Into::into)
            .map(|r| self.strip_namespace(r))
    }
}

impl Iterator for LooseThenPacked<'_, '_> {
    type Item = Result<Reference, Error>;

    fn next(&mut self) -> Option<Self::Item> {
        fn advance_to_non_private(iter: &mut Peekable<SortedLoosePaths>) {
            while let Some(Ok((_path, name))) = iter.peek() {
                if name.category().is_some_and(|cat| cat.is_worktree_private()) {
                    iter.next();

View on GitHub (pinned to e73179060b)