astral-sh/ruff · error

Workspace path is not valid UTF-8: {}

Error message

Workspace path is not valid UTF-8: {}

What it means

During workspace folder removal, the URI did convert to a path, but the resulting OS path contains bytes that are not valid UTF-8; SystemPathBuf::from_path_buf fails (session.rs:802). ty only stores Unicode paths, mirroring the startup check in lib.rs.

Source

Thrown at crates/ty_server/src/session.rs:802

    /// This removes the workspace folder and its associated project database,
    /// and clears diagnostics for any documents that were in the workspace.
    ///
    /// # Errors
    ///
    /// This returns an error if the workspace folder has already been removed
    /// or otherwise could not be found.
    pub(crate) fn remove_workspace_folder(
        &mut self,
        client: &Client,
        uri: &Uri,
    ) -> anyhow::Result<()> {
        tracing::info!("Removing workspace folder: {uri}");

        let path = uri
            .to_file_path()
            .map_err(|()| anyhow!("Workspace URI is not a file path: {uri}"))?;
        let workspace_path = SystemPathBuf::from_path_buf(path)
            .map_err(|path| anyhow!("Workspace path is not valid UTF-8: {}", path.display()))?;

        anyhow::ensure!(
            self.workspaces.unregister(&workspace_path),
            "Workspace not found: {uri}",
        );

        // Note that it is somewhat unclear whether we actually need to
        // clear diagnostics here. It seems that, at least in the case
        // of VS Code, it will auto-clear any diagnostics not found in
        // the workspace diagnostic response. Moreover, VS Code will
        // re-request workspace diagnostics after removing a workspace
        // folder.
        //
        // For now, we keep unconditionally clearing diagnostics on
        // opened text documents for reasons of good sense, but it's
        // possible that we don't even need to do that (when workspace
        // diagnostics are enabled).
        //

View on GitHub (pinned to 672bb4edf0)

Solutions

1. Rename the directory to a UTF-8 name, then re-add/remove the folder
2. Ensure the environment locale is UTF-8 so editors produce UTF-8 URIs
3. Avoid adding non-UTF-8 workspaces in the first place (the add path fails the same way)

// TS: reject non-UTF-8-decodable paths before sending folder changes
const isUtf8Path = (uri: string): boolean =>
  !decodeURIComponent(uri).includes('\uFFFD');
if (isUtf8Path(uri)) removeFolder(uri);

When it happens

Trigger: Removing a workspace folder whose decoded filesystem path holds non-UTF-8 bytes — e.g. a legacy-encoded directory name on Linux being removed by an editor that received it from a file-watcher.

Common situations: Projects under locale-encoded (Latin-1/Shift-JIS) directories, non-UTF-8 filenames surfaced by git or package managers, or URIs percent-encoded from raw non-UTF-8 bytes.

Related errors

• Workspace URI is not valid UTF8
• Workspace URI is not a file path: {uri}
• Workspace URI is not a file or directory: {uri:?}
• The current working directory `{}` contains non-Unicode char
• Failed to get the current working directory while creating a

AI-assisted analysis of astral-sh/ruff@672bb4edf0 (2026-08-16). Data as JSON: /api/errors/924d3bf43ea7e6a0. Report an issue: GitHub.