BoundaryML/baml · error

unknown axis `{name}`

Error message

unknown axis `{name}`

What it means

In the baml_type_macros derive/attribute parser (from_input), macro inputs referencing an axis are resolved by name against the declared axes list. If an ident doesn't match any declared axis, a syn::Error with a span on that ident is emitted at compile time.

Source

Thrown at baml_language/crates/baml_type_macros/src/parse.rs:301

    /// Whether the variant carries a `TyAttr` (a named `attr` field or a
    /// trailing tuple `TyAttr`). Attr-less template leaves get accessor
    /// fallbacks instead of a compile error.
    pub(crate) has_attr: bool,
}

impl Family {
    pub(crate) fn from_input(input: FamilyInput) -> syn::Result<Self> {
        let FamilyInput {
            axes,
            members,
            satellites,
            master,
        } = input;

        let axis_index = |name: &Ident| -> syn::Result<usize> {
            axes.iter()
                .position(|a| a == name)
                .ok_or_else(|| syn::Error::new(name.span(), format!("unknown axis `{name}`")))
        };
        let member_index = |name: &Ident| -> syn::Result<usize> {
            members.iter().position(|m| &m.name == name).ok_or_else(|| {
                syn::Error::new(name.span(), format!("unknown family member `{name}`"))
            })
        };

        let master_ident = master.ident.clone();

        let resolved_members = members
            .iter()
            .enumerate()
            .map(|(i, m)| {
                let includes = m
                    .includes
                    .iter()
                    .map(&axis_index)
                    .collect::<syn::Result<Vec<_>>>()?;

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Fix the axis name in the macro invocation to match a declared axis exactly
2. Check the family definition for the correct spelling of available axes
3. If the axis was renamed in a refactor, update all macro call sites to the new name

Example fix

// before
axis: modality,

// after
axis: modalities,

fn known_axis(name: &str, axes: &[&str]) -> Option<usize> {
    axes.iter().position(|a| a == name)
}

// Compile-time error; fix the source. To surface a friendlier message in build scripts:
match known_axis("modality", &axes) {
    Some(_) => {}
    None => panic!("axis `modality` not declared; available: {axes:?}"),
}

When it happens

Trigger: Expanding the macro with input that names an axis not present in the axes declaration — a misspelled axis name or referencing an axis removed from the family definition.

Common situations: Typos in macro invocations (e.g. 'modality' vs 'modalities'); refactoring axis names without updating all macro call sites; copy-pasting macro usage from another family.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• unknown family member `{name}`
• interned member `{name}` cannot be another member's child
• the master member cannot be interned: the master is the plai
• variant `{}` has more than one `#[axis(..)]`
• variant `{}` must declare exactly one `#[axis(..)]`

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/3377b44cbf17ca75. Report an issue: GitHub.