astral-sh/ruff · error

Failed to convert workspace URI to file path

Error message

Failed to convert workspace URI to file path: {workspace_uri}

What it means

When closing a workspace folder, Ruff must convert its URI to a file path to look up matching settings. URIs that are not `file://` (or that cannot be mapped to a path on the current platform) fail `to_file_path()` and produce this error, aborting the folder close.

Solutions

1. Only register/remove file:// workspace folders; virtual workspaces are unsupported by this code path.
2. Update Ruff — newer versions warn and ignore non-file workspaces instead of erroring.
3. If using remote development, open the folder through the remote extension so a mapped file URI is provided.

function isFileUri(uri) { return typeof uri === 'string' && uri.startsWith('file:'); }
if (removedFolders.some(f => !isFileUri(f.uri))) {
  console.warn('skipping non-file workspace folder removal:', f.uri);
}

function isConvertibleUri(u) { return typeof u === 'string' && u.startsWith('file://'); }

try {
  await connection.notify('workspace/didChangeWorkspaceFolders', { event: { removed } });
} catch (e) {
  if (String(e.message).includes('Failed to convert workspace URI')) {
    console.warn('non-file workspace ignored by Ruff');
  } else { throw e; }
}

When it happens

Trigger: A `workspace/didChangeWorkspaceFolders` remove event carries a non-file URI (untitled:, vfs:, remote authority URIs) or a file URI with a scheme/percent-encoding that cannot map to a filesystem path.

Common situations: Remote development (SSH/containers/devcontainers) where workspace URIs are virtual, untitled multi-root workspaces, or clients on Windows sending URIs Ruff's URI parser cannot convert.

Related errors

• Tried to remove non-existent workspace URI
• Workspace URI is not a file path
• Failed to format document
• InternalError
• InternalError

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/fa12d5e2839c55df. Report an issue: GitHub.

Appendix: source

Thrown at crates/ruff_server/src/session/index.rs:188

        notebook.update(cells, metadata, new_version, encoding)?;
        Ok(())
    }

    pub(super) fn open_workspace_folder(
        &mut self,
        uri: Uri,
        global: &GlobalClientSettings,
        client: &Client,
    ) -> crate::Result<()> {
        // TODO(jane): Find a way for workspace client settings to be added or changed dynamically.
        self.settings
            .register_workspace(&Workspace::new(uri), global, client)
    }

    pub(super) fn close_workspace_folder(&mut self, workspace_uri: &Uri) -> crate::Result<()> {
        let workspace_path = workspace_uri.to_file_path().map_err(|()| {
            anyhow!("Failed to convert workspace URI to file path: {workspace_uri}")
        })?;

        self.settings
            .remove(&workspace_path)
            .ok_or_else(|| anyhow!("Tried to remove non-existent workspace URI {workspace_uri}"))?;

        // O(n) complexity, which isn't ideal... but this is an uncommon operation.
        self.documents
            .retain(|uri, _| !Path::new(uri.path()).starts_with(&workspace_path));
        self.notebook_cells
            .retain(|_, uri| !Path::new(uri.path()).starts_with(&workspace_path));

        Ok(())
    }

    pub(super) fn make_document_ref(
        &self,
        key: DocumentKey,

View on GitHub (pinned to 26f38c119c)