What causes "BUG: This object must be a commit" in GitoxideLabs/gitoxide?

Check obj.kind == gix_object::Kind::Commit before calling, or use try_to_commit_ref_iter() which returns Option.

BUG: This object must be a commit

Error message

BUG: This object must be a commit

What it means

Object::to_commit_ref_iter() converts the object data into a CommitRefIter, which only works if the object kind is Commit. The expect panics for any other object kind, as documented in the method's # Panic section.

Solutions

Check obj.kind == gix_object::Kind::Commit before calling, or use try_to_commit_ref_iter() which returns Option.
Peel tags first with obj.peel_to_kind(gix_object::Kind::Commit)? to reach the underlying commit.
Handle the None from try_to_commit_ref_iter() with a proper error or branch.

Example fix

// before
let iter = obj.to_commit_ref_iter(); // panics if not a commit
// after
let Some(iter) = obj.try_to_commit_ref_iter() else {
    anyhow::bail!("object {} is not a commit", obj.id);
};

Defensive patterns

Strategy: type-guard

Validate before calling

if obj.kind == gix_object::Kind::Commit {
    let iter = obj.to_commit_ref_iter();
}

Type guard

fn as_commit_iter(obj: &gix::Object) -> Option<gix_object::CommitRefIter<'_>> { obj.try_to_commit_ref_iter() }

Prevention

Use try_to_commit_ref_iter() when the kind is uncertain.
Peel annotated tags before treating an object as a commit.
Validate kind early when reading user-supplied revisions.

When it happens

Trigger: Calling to_commit_ref_iter() on an object of kind Blob, Tree, or Tag.

Common situations: Resolving a ref or rev-spec that points to an annotated tag or tree; iterating mixed object lists without checking kinds; scripts reading loose objects by id.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at gix/src/object/mod.rs:192

    pub fn try_to_commit_ref(&self) -> Result<gix_object::CommitRef<'_>, conversion::Error> {
        gix_object::Data::new(&self.data, self.kind, self.id.kind())
            .decode()?
            .into_commit()
            .ok_or(conversion::Error::UnexpectedType {
                expected: gix_object::Kind::Commit,
                actual: self.kind,
            })
    }

    /// Obtain an iterator over commit tokens like in [`to_commit_iter()`][Object::try_to_commit_ref_iter()].
    ///
    /// # Panic
    ///
    /// - this object is not a commit
    pub fn to_commit_ref_iter(&self) -> gix_object::CommitRefIter<'_> {
        gix_object::Data::new(&self.data, self.kind, self.id.kind())
            .try_into_commit_iter()
            .expect("BUG: This object must be a commit")
    }

    /// Obtain a commit token iterator from the data in this instance, if it is a commit.
    pub fn try_to_commit_ref_iter(&self) -> Option<gix_object::CommitRefIter<'_>> {
        gix_object::Data::new(&self.data, self.kind, self.id.kind()).try_into_commit_iter()
    }

    /// Obtain a tag token iterator from the data in this instance.
    ///
    /// # Panic
    ///
    /// - this object is not a tag
    pub fn to_tag_ref_iter(&self) -> gix_object::TagRefIter<'_> {
        gix_object::Data::new(&self.data, self.kind, self.id.kind())
            .try_into_tag_iter()
            .expect("BUG: this object must be a tag")
    }

View on GitHub (pinned to e73179060b)