What causes "Unknown enum: {0}" in BoundaryML/baml?

Check that the enum named in the error is declared and spelled correctly.

BoundaryML/baml · error · ConvertError

Unknown enum: {0}

Error message

Unknown enum: {0}

What it means

ConvertError::UnknownEnum(DefKey) is raised in convert_ty when a SapTy::EnumVariant reference names an enum that has no entry in TypeCtx::enum_definitions. The library cannot resolve the enum variant without its EnumDefinition.

Source

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

    MapTy, MediaTy, NullTy, StringLiteralTy, StringTy, TyResolved, TyWithMeta, TypeAnnotations,
    TypeRefDb, UnionTy,
};

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),
}

View on GitHub (pinned to bd85ce9dee)

Solutions

Check that the enum named in the error is declared and spelled correctly.
Ensure the enum's defining module is included in the compilation context (SysOpContext.enum_definitions).
Replace the stale enum reference with an existing enum or a plain string type.

Example fix

// before
function Pick() -> Status.Active // Status not defined
// after
enum Status { Active Completed }
function Pick() -> Status.Active

Defensive patterns

Strategy: validation

Validate before calling

// Ensure every enum referenced by a variant type is declared
fn enum_exists(ctx: &TypeCtx, key: &DefKey) -> bool {
    ctx.enum_definitions.contains_key(key)
}

Try / catch

match result {
    Err(ConvertError::UnknownEnum(key)) => eprintln!("declare enum {key:?} before using its variants"),
    other => other,
}

Prevention

Declare enums in the same or an imported module before referencing their variants.
Use static checks/linting to catch dangling enum references.
Grep for variant usages before deleting an enum.

When it happens

Trigger: Converting a type like EnumVariant(MyEnum, SomeVariant) via TypeCtx::build_db / convert_ty when MyEnum was never declared or not loaded into the context.

Common situations: A field references an enum variant of an enum defined in an unloaded module; a typo in the enum name; an enum deleted during refactoring while a function return type still uses it.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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