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.

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.

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