BoundaryML/baml · error · FsPathError

native path is not valid Unicode: {0:?}

Error message

native path is not valid Unicode: {0:?}

What it means

FsPathError::NonUnicode is returned when a native path contains bytes that cannot be decoded as valid UTF-8 (common on Linux where paths are arbitrary bytes). baml_path requires Unicode-native paths because VFS URIs are string-based.

Source

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

        validate_vfs_path(&path)?;
        Ok(Self(path))
    }

    pub fn as_str(&self) -> &str {
        &self.0
    }

    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(());

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Rename the offending file/directory to a valid UTF-8 name (e.g. using convmv).
2. Recreate the file with a Unicode-safe name and restore its contents.
3. Exclude non-UTF-8 paths from the project/workspace indexing.
4. Find offenders with: find . | grep -P '[\x80-\xFF]' (after confirming encoding).

Example fix

// before
convmv -f latin1 -t utf-8 --notest badname.baml  // if needed
// after renaming
let vfs = FsPath::new(path).to_vfs()?; // succeeds

fn is_utf8_path(p: &std::path::Path) -> bool {
    std::str::from_utf8(
        std::os::unix::ffi::OsStrExt::as_bytes(p.as_os_str())
    ).is_ok()
}

fn valid_unicode_path(p: &std::path::Path) -> Option<&str> {
    p.to_str()
}

When it happens

Trigger: Converting a PathBuf whose OS string contains invalid UTF-8 (e.g. a filename with raw 0x80-0xFF bytes from another encoding) into a VFS path; files created by tools using legacy locale encodings.

Common situations: Files with names in Latin-1/Shift-JIS created by older tools; filenames with mojibake after a bad unzip; projects synced from systems with non-UTF-8 filesystem encodings.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• diagnostic message style code is a valid Unicode variation s
• cannot determine directory of current executable
• `{}` doesn't look like it belongs to a BAML project — no `ba
• a source root already exists at this path
• no filesystem is attached to this server ({})

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