BoundaryML/baml · error · ConvertError

Unknown name (could not determine if it was a class, enum, o

Error message

Unknown name (could not determine if it was a class, enum, or type alias): {0}

What it means

ConvertError::UnknownName(DefKey) is raised in convert_type_alias when an alias's inner type resolves to Ty::Unresolved(inner_name) and the name is not found among classes, enums, or type aliases. The converter cannot determine what kind of named type it is.

Source

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

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;

/// Contains stuff from [`sys_types::SysOpContext`] that we need for converting to the sap model.
///

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Declare the missing name as a class, enum, or type alias in your BAML sources.
2. Check spelling — the error means the name matches none of the three known kinds.
3. Ensure all modules defining referenced types are loaded into the SysOpContext before building the SAP model.

Example fix

// before
type Result = UnknownThing
// after
class UnknownThing { ok: bool }
type Result = UnknownThing

// A name must be exactly one of: class, enum, or alias
fn name_is_known(ctx: &TypeCtx, key: &DefKey) -> bool {
    ctx.class_definitions.contains_key(key)
        || ctx.enum_definitions.contains_key(key)
        || ctx.type_alias_definitions.contains_key(key)
}

match result {
    Err(ConvertError::UnknownName(key)) => eprintln!("{key:?} is not a class, enum, or type alias — declare it"),
    other => other,
}

When it happens

Trigger: TypeCtx::build_db converting a type alias whose flattened inner reference names something absent from all three definition maps (class_definitions, enum_definitions, type_alias_definitions).

Common situations: A dangling reference after deleting a class/enum/alias; a name typo; a type from an unloaded module referenced by an alias.

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 type alias: {0}
• Non-parsable type: {0:?}
• Could not add a type to the database as the name `{0}` is al

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