BoundaryML/baml · error · anyhow::Error

Failed to create document key for file {}: {}

Error message

Failed to create document key for file {}: {}

What it means

BamlProject.load_files throws this when DocumentKey::from_path fails for a gathered file, i.e. a file found under the workspace root cannot be converted into a valid document key (typically because its path cannot be resolved/normalized relative to the root or has an invalid format). The underlying cause is embedded in the message.

Source

Thrown at engine/language_server/src/baml_project/mod.rs:281

        }
        self.cached_runtime = None;
    }

    /// Load files into the current state. Also return the newly loaded files.
    pub fn load_files(&mut self) -> anyhow::Result<HashMap<DocumentKey, TextDocument>> {
        let workspace_file_paths = gather_files(&self.root_dir_name, false).map_err(|e| {
            anyhow::anyhow!(
                "Failed to gather files from directory {}: {}",
                self.root_dir_name.display(),
                e
            )
        })?;
        let workspace_files = workspace_file_paths
            .into_iter()
            .map(|file_path| {
                let document_key = DocumentKey::from_path(&self.root_dir_name, &file_path)
                    .map_err(|e| {
                        anyhow::anyhow!(
                            "Failed to create document key for file {}: {}",
                            file_path.display(),
                            e
                        )
                    })?;
                let contents = std::fs::read_to_string(&file_path).map_err(|e| {
                    anyhow::anyhow!("Failed to read file {}: {}", file_path.display(), e)
                })?;
                let text_document = TextDocument::new(contents, 0);
                Ok((document_key, text_document))
            })
            .collect::<anyhow::Result<HashMap<_, _>>>()?;

        let project_files = workspace_files.clone();

        self.files = project_files;
        Ok(workspace_files)
    }

View on GitHub (pinned to bd85ce9dee)

Solutions

  1. Identify the offending file from the path embedded in the error message and rename it to a normal, valid path
  2. Remove or fix broken symlinks under the workspace root
  3. Ensure files are on a native filesystem (avoid problematic network mounts) and re-run
  4. Re-gather the project cleanly (delete generated/temp files with unusual names)

Example fix

// before
$ mv 'my file?.baml' baml_src/  # invalid chars break DocumentKey::from_path
// after
$ mv 'my file?.baml' baml_src/my_file.baml
Defensive patterns

Strategy: validation

Validate before calling

// Skip files that cannot form a valid document key before load:
let valid = DocumentKey::from_path(&root, &path).is_ok();
if !valid { eprintln!("Skipping unresolvable path: {}", path.display()); }

Try / catch

match project.load_files() {
    Err(e) if e.to_string().contains("Failed to create document key") => {
        eprintln!("Bad path in workspace: {e}; rename or remove the file.");
    }
    r => r,
}

Prevention

When it happens

Trigger: load_files() iterating gathered file paths where a path is relative or malformed, escapes the root, or from_path rejects it (invalid URI/path conversion for that file).

Common situations: Weird filenames (spaces, unicode, control characters) or unusual symlinks in the project; files generated by tools with pathological names; platform path mismatches (Windows vs Unix separators) in synced workspaces.

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

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