BoundaryML/baml · error · FsPathError

invalid VFS path: {0}

Error message

invalid VFS path: {0}

What it means

FsPathError::InvalidVfsPath is thrown by the baml_path crate when a path string cannot be interpreted as a valid virtual filesystem (VFS) path. The FsPathError enum also covers non-Unicode native paths and unsupported native path prefixes (like Windows verbatim prefixes), and every variant is converted into a vfs::VfsError via the From impl. It means the caller supplied a path that does not map cleanly onto the VFS abstraction.

Source

Thrown at baml_language/crates/baml_path/src/lib.rs:42

    }

    pub fn into_string(self) -> String {
        self.0
    }
}

#[derive(Debug, thiserror::Error)]
pub enum FsPathError {
    #[error("native path is not absolute: {0}")]
    NotAbsolute(PathBuf),

    #[error("native path is not valid Unicode: {0:?}")]
    NonUnicode(PathBuf),

    #[error("unsupported native path prefix: {0}")]
    UnsupportedPrefix(PathBuf),

    #[error("invalid VFS path: {0}")]
    InvalidVfsPath(String),
}

impl From<FsPathError> for vfs::VfsError {
    fn from(error: FsPathError) -> Self {
        vfs::VfsError::from(vfs::error::VfsErrorKind::Other(error.to_string()))
    }
}

fn validate_vfs_path(path: &str) -> Result<(), FsPathError> {
    if path == "/" {
        return Ok(());
    }

    let invalid = !path.starts_with('/')
        || path.ends_with('/')
        || path
            .split('/')

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Print and inspect the exact offending path embedded in the error message
2. Normalize the path (e.g. std::fs::canonicalize or path cleaning) before passing it to the VFS API
3. Strip unsupported prefixes (e.g. Windows verbatim \\?\) and use plain absolute paths
4. Ensure paths are valid UTF-8; reject or convert OsStr paths that are not Unicode
5. Validate the path against the target platform's rules before calling the library

Example fix

// before
let p = std::path::Path::new("\\\\?\\C:\\tmp\\baml");
vfs_root.join(p);
// after
let p = std::path::PathBuf::from("C:\\tmp\\baml");
let canonical = std::fs::canonicalize(&p)?;
vfs_root.join(canonical);

fn is_vfs_safe(p: &Path) -> bool {
    p.is_absolute()
        && p.to_str().map(|s| !s.is_empty() && !s.contains("\\\\?!\\\\")).unwrap_or(false)
}

fn valid_vfs_path(p: &Path) -> Option<&str> { p.to_str().filter(|s| !s.is_empty()) }

match vfs_op(path) {
    Err(e) if e.to_string().starts_with("invalid VFS path") => warn!("bad path: {path:?}"),
    Err(e) => return Err(e),
    Ok(v) => Ok(v),
}

When it happens

Trigger: Calling a baml_path API with a malformed or empty path string, a path with an unsupported native prefix, or a path containing components the VFS cannot represent; the resulting FsPathError is propagated (usually converted to vfs::VfsError::Other) as 'invalid VFS path: {path}'.

Common situations: Using Windows verbatim or UNC prefixes (\\?\C\...) that the VFS layer rejects, passing an empty or relative path where an absolute canonical path is required, or constructing paths programmatically with stray separators/invalid characters on cross-platform builds.

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

• native path is not absolute: {0}
• unsupported native path prefix: {0}
• Expected --from '{}' to be a baml_src/ directory, but it doe
• Expected --from '{}' to be a baml_src/ directory, but it is
• Failed to create document key for file {}: {}

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