BoundaryML/baml · error · SourceRootError

dependency name `{name}` is reserved

Error message

dependency name `{name}` is reserved

What it means

SourceRootError::ReservedDependencyName is returned by ProjectDatabase::add_dependency when the edge name is one no package may declare: a stdlib package's name (already an implicit dependency edge of every package) or a source-level qualifier like `root` or `env`. The database reserves these names to keep name resolution unambiguous.

Source

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

    #[must_use]
    pub fn depending_on(mut self, dependencies: Vec<Dependency>) -> Self {
        self.dependencies = dependencies;
        self
    }
}

/// Why [`ProjectDatabase::add_source_root`] or
/// [`ProjectDatabase::add_dependency`] refused.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum SourceRootError {
    /// 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

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Rename the dependency edge to a non-reserved name (avoid stdlib package names and the `root`/`env` qualifiers).
2. Match on SourceRootError::ReservedDependencyName and surface a clear message telling the user which name is reserved and why.
3. Pre-validate dependency names in your tool against the reserved set before calling add_dependency.
4. If the intent is to use the stdlib package, drop the explicit dependency — it is already implicit.

Example fix

// before
db.add_dependency(root, name!("env"), &dep_root).unwrap();
// after
let alias = name!("project_env"); // any non-reserved name
db.add_dependency(root, alias, &dep_root)?;

const RESERVED: &[&str] = &["root", "env", /* stdlib package names */];
if RESERVED.contains(&dep_name.as_str()) {
    return Err(format!("dependency name `{dep_name}` is reserved"));
}

match db.add_dependency(root, dep_name, &dep_root) {
    Err(SourceRootError::ReservedDependencyName { name }) => {
        eprintln!("`{name}` is reserved (stdlib or source qualifier); choose another name");
    }
    other => other?,
}

When it happens

Trigger: Calling add_dependency(root, name, path) where name is a stdlib package name or "root"/"env"; or a build tool deriving dependency edges from a manifest that declares a dependency with one of these reserved identifiers.

Common situations: A project file or manifest that names a local package the same as a stdlib package (e.g. `math`, `gen`) or uses `root`/`env` as a dependency key; build scripts auto-registering dependencies from directory names that collide.

Related errors

• a source root already exists at this path
• all ingress capacities and the response reservation must be
• read capacity must fit inside normal capacity
• one response reservation must fit in the outbound byte capac
• combined normal and reserved capacity overflowed usize

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