GitoxideLabs/gitoxide · error

BUG: need tag

Error message

BUG: need tag

What it means

Object::to_tag_ref() wraps try_to_tag_ref() and expects success. It panics when the object is not a tag or the tag object fails to decode, as stated in its # Panic docs. It is the non-fallible convenience for callers who already know the kind.

Solutions

1. Check obj.kind == gix_object::Kind::Tag before converting.
2. Use try_to_tag_ref() and handle the Result gracefully.
3. Peel/validate via peel_to_kind(gix_object::Kind::Tag)? first.

Example fix

// before
let tag = obj.to_tag_ref(); // panics if not a tag
// after
let tag = obj.try_to_tag_ref()
    .ok_or_else(|| anyhow::anyhow!("expected tag, got {:?}", obj.kind))?;

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

fn try_tag(obj: &gix::Object) -> Option<gix_object::TagRef<'_>> { obj.try_to_tag_ref().ok() }

When it happens

Trigger: Calling to_tag_ref() on an object of kind Commit, Tree, or Blob; calling it on a malformed tag object whose decode fails.

Common situations: Resolving refs that point at commits rather than annotated tags; user-supplied object ids; repositories with corrupt or partially-written tag objects.

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

• BUG: this object must be a tag
• BUG: need a commit
• BUG: This object must be a commit
• ' ' is not a valid configuration key
• Cannot use iter_v1() on index of type

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

Appendix: source

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

    }

    /// 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<'_> {
        self.try_to_tag_ref().expect("BUG: need tag")
    }

    /// Obtain a fully parsed tag object whose fields reference our data buffer.
    pub fn try_to_tag_ref(&self) -> Result<gix_object::TagRef<'_>, conversion::Error> {
        gix_object::Data::new(&self.data, self.kind, self.id.kind())
            .decode()?
            .into_tag()
            .ok_or(conversion::Error::UnexpectedType {
                expected: gix_object::Kind::Tag,
                actual: self.kind,
            })
    }

    /// Return the attached id of this object.
    pub fn id(&self) -> Id<'repo> {
        Id::from_id(self.id, self.repo)
    }
}

View on GitHub (pinned to e73179060b)