BoundaryML/baml · error · SourceRootError

invalid package interface

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.

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

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

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

Appendix: 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)