BoundaryML/baml · error · anyhow::Error

Type alias not found: {name}

Error message

Type alias not found: {name}

What it means

During IR construction, recursive/named type references must be expanded by looking up the alias in the resolved type alias table. If the name is absent from resolved_type_aliases, BAML bails with this error. It means a type reference points to an alias that was never defined or never resolved.

Source

Thrown at engine/baml-lib/baml-core/src/ir/repr.rs:145

            TypeGeneric::Tuple(type_generics, _) => {
                type_generics.iter_mut().for_each(|t| self.update_type(t))
            }
            TypeGeneric::Arrow(arrow_generic, _) => {
                self.update_type(&mut arrow_generic.return_type)
            }
            TypeGeneric::Union(union_type_generic, _) => union_type_generic
                .iter_skip_null_mut()
                .iter_mut()
                .for_each(|t| self.update_type(t)),
        }
    }
}

impl TypeLookups for IntermediateRepr {
    fn expand_recursive_type(&self, name: &str) -> anyhow::Result<&TypeIR> {
        match self.pass2_repr.resolved_type_aliases.get(name) {
            Some(ty) => Ok(ty),
            None => anyhow::bail!("Type alias not found: {name}"),
        }
    }
}

#[derive(Debug)]
pub struct TopLevelAssignment {
    pub name: Node<String>,
    pub expr: Node<Expr<ExprMetadata>>,
}

#[derive(Clone, Debug)]
pub struct ClassConstructor {
    pub class_name: Node<String>,
    pub fields: Vec<Node<ClassConstructorField>>,
}

#[derive(Clone, Debug)]
pub enum ClassConstructorField {

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Check the alias name in the error against your .baml type alias definitions for typos.
2. Ensure the file defining the alias is part of the BAML source loaded by the generator.
3. Fix recursive/circular alias definitions so every referenced alias actually resolves.
4. Run baml CLI generate to see full diagnostics of unresolved types.

Example fix

// before
type UserList = Users[]
// after
type UserList = User[]

# pseudo-check over .baml sources before compiling:
# collect all 'type X = ...' aliases, then verify every referenced alias exists
import re
aliases = set(re.findall(r'^\s*type\s+(\w+)\s*=', src, re.M))
refs = set(re.findall(r'\b([A-Z]\w+)\b', src))
unresolved = refs - aliases - PRIMITIVES  # e.g. {"string","int","float","bool"}

match ir.expand_recursive_type(name) {
    Ok(ty) => ty,
    Err(e) if e.to_string().starts_with("Type alias not found") => {
        eprintln!("define or fix alias '{name}' before generating");
        std::process::exit(1);
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: expand_recursive_type(name) called via TypeLookups for IntermediateRepr when the referenced type alias (e.g. from a recursive type definition like `type Foo = Bar[] & Foo` or an alias referencing itself/another alias) is not present in the resolved alias map.

Common situations: Typo in a type alias name; referencing an alias defined in another BAML file not included in the source; recursive type cycles that failed earlier resolution; renamed alias while old references remain.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Expression functions must have a return type
• Expression functions must have return type.
• Field type uses unresolvable local identifier {}
• Type mismatch: {message}
• Schema inconsistency: {message}

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