GitoxideLabs/gitoxide · error

valid macro names are always UTF8 and this was verified

Error message

valid macro names are always UTF8 and this was verified

What it means

During `MetadataCollection::update_from_list`, macro assignment patterns have their pattern text converted with `to_str().expect("valid macro names are always UTF8 and this was verified")`. Macro names are validated as UTF-8 earlier in parsing, so this panic means a non-UTF-8 macro name reached the macro registration stage — a broken invariant between the parser's validation and this consumer.

Solutions

  1. Ensure macro names in .gitattributes are valid UTF-8 (they must be valid git attribute names anyway)
  2. Upgrade gix-attributes and gix-glob together to versions from the same release
  3. If you read attribute buffers yourself before add_patterns_buffer, validate UTF-8 of pattern text first
  4. Report upstream with the offending .gitattributes content

Example fix

// caller-side guard before feeding buffers
let text = std::str::from_utf8(&buf)
    .expect("attribute file must be UTF-8 for macro names");
search.add_patterns_buffer(text.as_bytes(), source, root, &mut collection, true);
Defensive patterns

Strategy: validation

Validate before calling

// validate attribute buffers before handing them to the search
fn valid_utf8_attributes(buf: &[u8]) -> bool { std::str::from_utf8(buf).is_ok() }

Try / catch

std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| update_from_list(...)))

Prevention

When it happens

Trigger: Loading an attributes file/buffer whose macro definition (`[attr]name ...`) contains non-UTF-8 bytes in the macro name, bypassing the parser-level UTF-8 verification — practically only via a parser regression or a mismatched gix-glob/gix-attributes version pair.

Common situations: Repositories with binary junk in .gitattributes files combined with a gix version whose parser failed to validate macro names; patched crates where validation was removed.

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/6c08ef50090ad8da. Report an issue: GitHub.

Appendix: source

Thrown at gix-attributes/src/search/outcome.rs:276

    }
}

/// Mutation
impl MetadataCollection {
    /// Assign order ids to each attribute either in macros (along with macros themselves) or attributes of patterns, and store
    /// them in this collection.
    ///
    /// Must be called before querying matches.
    pub fn update_from_list(&mut self, list: &mut gix_glob::search::pattern::List<Attributes>) {
        for pattern in &mut list.patterns {
            match &mut pattern.value {
                Value::MacroAssignments { id: order, assignments } => {
                    *order = self.id_for_macro(
                        pattern
                            .pattern
                            .text
                            .to_str()
                            .expect("valid macro names are always UTF8 and this was verified"),
                        assignments,
                    );
                }
                Value::Assignments(assignments) => {
                    self.assign_order_to_attributes(assignments);
                }
            }
        }
    }
}

/// Access
impl MetadataCollection {
    /// Return an iterator over the contents of the map in an easy-to-consume form.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &Metadata)> {
        self.name_to_meta.iter().map(|(k, v)| (k.as_str(), v))
    }
}

View on GitHub (pinned to e73179060b)