astral-sh/ruff · error

Workspace URI is not valid UTF8

Error message

Workspace URI is not valid UTF8

What it means

During workspace registration, the URI converted to an OS path but that path is not valid UTF-8, so SystemPathBuf::from_path_buf fails (session.rs:1543). The code comment notes this is considered near-impossible because the path came from a Uri, but percent-encoded non-UTF-8 bytes can still produce it.

Source

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

    ///
    /// This returns `true` when this workspace is added and `false`
    /// when it has already been added.
    ///
    /// It's the caller's responsibility to later call
    /// [`Session::request_uninitialized_workspace_folder_configurations`] with
    /// the resolved settings for this workspace. Registering and initializing
    /// a workspace is a two-step process because the workspace are announced
    /// to the server during the `initialize` request, but the resolved
    /// settings are only available after the client has responded to the
    /// `workspace/configuration` request.
    fn register(&mut self, uri: Uri) -> anyhow::Result<bool> {
        let path = uri
            .to_file_path()
            .map_err(|()| anyhow!("Workspace URI is not a file or directory: {uri:?}"))?;

        // Realistically I don't think this can fail because we got the path from a Uri
        let system_path = SystemPathBuf::from_path_buf(path)
            .map_err(|_| anyhow!("Workspace URI is not valid UTF8"))?;

        if self.workspaces.contains_key(&system_path) {
            return Ok(false);
        }

        self.workspaces.insert(
            system_path,
            Workspace {
                uri,
                settings: Arc::new(WorkspaceSettings::default()),
                initialized: false,
            },
        );
        Ok(true)
    }

    /// Unregisters a workspace folder at the given path.
    ///

View on GitHub (pinned to 672bb4edf0)

Solutions

1. Rename the directory to a UTF-8 name before opening it as a workspace
2. Run the editor under a UTF-8 locale so it generates UTF-8 URIs
3. Skip adding the offending folder and open a differently-located copy

// TS: skip folders whose decoded path is not valid UTF-8
const decodes = (uri: vscode.Uri): boolean => {
  try { Buffer.from(uri.fsPath, 'utf8'); return !uri.fsPath.includes('\uFFFD'); }
  catch { return false; }
};

When it happens

Trigger: Adding a workspace folder whose decoded path bytes are invalid UTF-8 — practically only reachable via URIs percent-encoded from raw non-UTF-8 filenames.

Common situations: Legacy-encoded project directories on Linux, files created by old tools with locale-encoded names, or synthetic URIs constructed from raw OS paths.

Related errors

• Workspace path is not valid UTF-8: {}
• 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/fccf6f9c3dfc5e38. Report an issue: GitHub.