BoundaryML/baml · error · SourceRootError

invalid package interface: {message}

Error message

invalid package interface: {message}

What it means

Part of `SourceRootError`. Thrown when the interface bytes attached to a source root via `served_from(bytes)` are not a valid `PackageInterface` artifact (the borsh-serialized precompiled interface for the package). The database cannot reconstruct the package's public surface from them.

Source

Thrown at baml_language/crates/baml_db/src/db.rs:103

    /// A live root already sits at this (canonical) path.
    #[error("a source root already exists at this path")]
    PathTaken(SourceRoot),
    /// The edge name is one no package may declare: a stdlib package's name
    /// (already an implicit edge of every package) or a source-level
    /// qualifier (`root`, `env`).
    #[error("dependency name `{name}` is reserved")]
    ReservedDependencyName { name: Name },
    /// The root already has an edge under this name.
    #[error("dependency `{name}` is declared twice")]
    DuplicateDependencyName { name: Name },
    /// The edge names a root that is not live in this database.
    #[error("dependency `{name}` names a source root that does not exist")]
    UnknownDependencyRoot { name: Name },
    /// The edge would make the dependency graph cyclic.
    #[error("dependency `{name}` would form a dependency cycle")]
    DependencyCycle { name: Name },
    /// The interface bytes are not a valid `PackageInterface` artifact.
    #[error("invalid package interface: {message}")]
    InvalidInterface { message: String },
}

/// The main database for BAML projects.
///
/// `ProjectDatabase` owns the Salsa storage directly and implements all the
/// compiler `Db` traits. It provides high-level APIs for:
/// - Source-root management (add/remove roots, longest-prefix lookup)
/// - File management within a root (add/update/remove files)
/// - Diagnostics collection via `check()`
///
/// ## Example
///
/// ```ignore
/// let mut db = ProjectDatabase::new();
/// db.ensure_stdlib_sources();
/// let root = db.add_source_root(SourceRootSpec::new("/my/project", SourceRootKind::Workspace))?;
/// db.add_or_update_file_in(root, Path::new("/my/project/main.baml"), "class Foo {}");

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Regenerate the precompiled stdlib interface bytes with the matching compiler version.
2. Verify the bytes are the full borsh-encoded `PackageInterface` for the package.
3. Ensure the artifact pipeline isn't truncating or corrupting the byte blobs.

Example fix

// before
let bytes = read_file("stdlib/core.interface.bin"); // stale v0.1 artifact
// after
let bytes = regenerate_interface("core"); // built with current compiler
spec.served_from(bytes)

fn interfaces_look_valid(map: &BTreeMap<String, Vec<u8>>) -> bool {
    !map.is_empty() && map.values().all(|b| !b.is_empty())
}

// add_source_root returns Result; treat InvalidInterface as a corrupted-artifact case
match db.add_source_root(spec) {
    Err(SourceRootError::InvalidInterface { message }) => eprintln!("regenerate interface bytes: {message}"),
    Err(e) => eprintln!("root error: {e}"),
    Ok(root) => root,
}

When it happens

Trigger: Calling `SourceRootSpec::served_from` with bytes that fail `PackageInterface` deserialization, then `add_source_root`; typically happens when `StdlibProvenance::Interface` bytes come from `ensure_precompiled_stdlib`.

Common situations: Stale or truncated precompiled stdlib artifacts from an older compiler version; bytes corrupted in transit/storage; passing arbitrary bytes (e.g. source text) instead of serialized interfaces.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• variant `{}` requires an explicit discriminant to stabilize
• Future cannot be deserialized
• UnscheduledFuture cannot be serialized
• RustData cannot be serialized
• HostClosure cannot be serialized

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