What causes "BUG: this object must be a tag" in GitoxideLabs/gitoxide?

Verify obj.kind == gix_object::Kind::Tag before calling to_tag_ref_iter().

BUG: this object must be a tag

Error message

BUG: this object must be a tag

What it means

Object::to_tag_ref_iter() converts the object into a TagRefIter, valid only for objects of kind Tag. The expect panics otherwise, matching the documented # Panic condition. Internal callers (peel_to_kind, peel_tags_to_end) rely on it after filtering to tag objects.

Solutions

Verify obj.kind == gix_object::Kind::Tag before calling to_tag_ref_iter().
Use try_to_tag_ref_iter() which returns Option and handle the None case.
Peel or branch by kind before invoking tag-specific iteration.

Example fix

// before
let tag = obj.to_tag_ref_iter(); // panics if not a tag
// after
if obj.kind == gix_object::Kind::Tag {
    let tag = obj.to_tag_ref_iter();
    // ...
}

Defensive patterns

Strategy: type-guard

Validate before calling

if obj.kind == gix_object::Kind::Tag {
    let tag = obj.to_tag_ref_iter();
}

Type guard

fn as_tag_iter(obj: &gix::Object) -> Option<gix_object::TagRefIter<'_>> { obj.try_to_tag_ref_iter() }

Prevention

Use try_to_tag_ref_iter() when the kind is uncertain.
Remember lightweight tags point at commits, not tag objects - check kind.
Branch on Object::kind before tag-specific parsing.

When it happens

Trigger: Calling to_tag_ref_iter() on an object of kind Commit, Tree, or Blob; calling peel_to_kind(Tag)/peel_tags_to_end logic on unexpected object kinds in custom code paths.

Common situations: Walking objects without checking kind; assuming a lightweight ref points to an annotated tag object; deserializing arbitrary object ids from user input.

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/4dc5bfd3589fd786. Report an issue: GitHub.

Appendix: source

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

        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")
    }

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

    /// Obtain a tag object from the data in this instance.
    ///
    /// # Panic
    ///
    /// - this object is not a tag
    /// - the tag could not be decoded
    pub fn to_tag_ref(&self) -> gix_object::TagRef<'_> {

View on GitHub (pinned to e73179060b)