BoundaryML/baml · error · ConvertError

Unknown type alias: {0}

Error message

Unknown type alias: {0}

What it means

ConvertError::UnknownTypeAlias(DefKey) is raised when flattening a SapTy::TypeAlias reference (convert_ty, get_field_attrs, field_type_is_nullable) and the alias name has no entry in TypeCtx::type_alias_definitions. Aliases must be flattenable to their underlying type.

Source

Thrown at baml_language/crates/bex_sap/src/sap_model/convert.rs:36

};

impl crate::sap_model::TypeIdent for DefKey {}

#[derive(thiserror::Error, Debug)]
pub enum ConvertError {
    #[error("Failed to parse float: {0}")]
    ParseFloat(#[from] std::num::ParseFloatError),
    #[error("Unknown media kind")]
    UnknownMediaKind,
    #[error("Float literals cannot be parsed")]
    FloatLiteral,
    #[error("Non-parsable type: {0:?}")]
    NonParsableType(Box<SapTy>),
    #[error("Unknown class: {0}")]
    UnknownClass(DefKey),
    #[error("Unknown enum: {0}")]
    UnknownEnum(DefKey),
    #[error("Unknown type alias: {0}")]
    UnknownTypeAlias(DefKey),
    #[error("Unknown name (could not determine if it was a class, enum, or type alias): {0}")]
    UnknownName(DefKey),
    #[error("Could not add a type to the database as the name `{0}` is already present")]
    AlreadyPresent(DefKey),
    #[error("Recursion depth exceeded for {0}")]
    RecursionDepthExceeded(&'static str),
    #[error("Unions must be flattened")]
    UnflattenedUnion,
    /// Something like `type A = B; type B = A;` is invalid.
    #[error("Recursive type alias without indirection: {0}")]
    DirectRecursiveTypeAlias(DefKey),
    #[error("Internal error (please report): {0}")]
    InternalError(&'static str),
}

const MAX_RECURSION_DEPTH: usize = 16;

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Verify the alias name in the error is declared with a `type X = ...` statement and spelled correctly.
2. Include the module containing the alias in the compilation context passed to TypeCtx.
3. Inline the alias's underlying type where the stale reference occurs.

Example fix

// before
type UserId = MissingBase
// after
type UserId = int

// Confirm each alias referenced by types resolves in the alias table
fn alias_exists(ctx: &TypeCtx, key: &DefKey) -> bool {
    ctx.type_alias_definitions.contains_key(key)
}

match result {
    Err(ConvertError::UnknownTypeAlias(key)) => eprintln!("declare `type {key:?} = ...` or inline its value"),
    other => other,
}

When it happens

Trigger: TypeCtx::build_db or field-attribute derivation encounters a type alias reference (or a class field typed by an alias) whose DefKey is absent from the alias definition map.

Common situations: An alias declared in a module not included in the context; a typo in an alias name; an alias removed while other types still reference it; hand-constructed SapTy::TypeAlias values pointing at nonexistent keys.

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

• Unknown class: {0}
• Unknown enum: {0}
• Unknown name (could not determine if it was a class, enum, o
• Recursion depth exceeded for {0}
• Recursive type alias without indirection: {0}

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