What causes "Class with name {name} already exists" in BoundaryML/baml?

Use tb.class(rt, name) to retrieve and modify the existing class instead of add_class

Class with name {name} already exists

Error message

Class with name {name} already exists

What it means

TypeBuilder::add_class refuses to create a class whose name is already defined in the runtime IR. Class names must be unique in BAML; attempting to add a duplicate bails with this error instead of silently overwriting the existing definition.

Source

Thrown at engine/language_client_cffi/src/raw_ptr_wrapper/type_builder/objects.rs:74

impl TypeBuilder {
    pub fn add_enum(&self, rt: &BamlRuntime, name: &str) -> anyhow::Result<EnumBuilder> {
        match rt.ir.find_enum(name) {
            Ok(_) => {
                anyhow::bail!("Enum with name {name} already exists");
            }
            Err(_) => {
                let _ = self.type_builder.upsert_enum(name);
                let builder = EnumBuilder::new(self.type_builder.clone(), name.to_string());
                Ok(builder.mode(NodeRW::ReadWrite))
            }
        }
    }

    pub fn add_class(&self, rt: &BamlRuntime, name: &str) -> anyhow::Result<ClassBuilder> {
        match rt.ir.find_class(name) {
            Ok(_) => {
                anyhow::bail!("Class with name {name} already exists");
            }
            Err(_) => {
                let _ = self.type_builder.upsert_class(name);
                let builder = ClassBuilder::new(self.type_builder.clone(), name.to_string());
                Ok(builder.mode(NodeRW::ReadWrite))
            }
        }
    }

    pub fn class(&self, rt: &BamlRuntime, name: &str) -> anyhow::Result<ClassBuilder> {
        match rt.ir.find_class(name) {
            Ok(cls) => {
                let _ = self.type_builder.upsert_class(name);
                let builder = ClassBuilder::new(self.type_builder.clone(), name.to_string());
                if !cls.item.attributes.dynamic() {
                    Ok(builder.mode(NodeRW::ReadOnly))
                } else {
                    Ok(builder.mode(NodeRW::ReadWrite))

View on GitHub (pinned to bd85ce9dee)

Solutions

Use tb.class(rt, name) to retrieve and modify the existing class instead of add_class
Guard with an existence check before calling add_class
Rename the new class to a unique name

Example fix

// before
let cb = tb.add_class(rt, "Resume")?; // fails if Resume exists
// after
let cb = match tb.class(rt, "Resume") {
    Ok(cb) => cb,
    Err(_) => tb.add_class(rt, "Resume")?,
};

Defensive patterns

Strategy: try-catch

Validate before calling

# caller side: check before add
if class_exists(rt, "Resume"):
    cb = tb.class("Resume")
else:
    cb = tb.add_class(rt, "Resume")

Try / catch

try:
    cb = tb.add_class(rt, name)
except Exception as e:
    if "already exists" in str(e):
        cb = tb.class(name)
    else:
        raise

Prevention

Build dynamic classes idempotently: get-or-create pattern
Avoid re-running builder registration on every request; build once and reuse
Prefix dynamic class names to avoid clashing with .baml-declared classes

When it happens

Trigger: Calling tb.add_class(rt, "Name") when a class named 'Name' already exists in the compiled BAML IR or was previously added via the same TypeBuilder.

Common situations: Dynamic class creation colliding with classes declared in .baml files; non-idempotent builder initialization re-run on each request; duplicated dynamic class registration.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

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