What causes "failed to convert URL to URI: {err}" in biomejs/biome?

Inspect the failing file path (from the surrounding navigation request or logs) for unusual characters or escape sequences and rename/normalize the file.

biomejs/biome · error · LspError

failed to convert URL to URI: {err}

Error message

failed to convert URL to URI: {err}

What it means

Second stage of uri_from_path: after Url::from_file_path succeeds, the URL string is re-parsed into the tower-lsp Uri type with Uri::from_str (navigation.rs:139-140). This fails only when the constructed file:// URL violates the stricter Uri grammar - for example unusual percent-encoding sequences or characters the url crate accepts but the Uri parser rejects. It shares its parent function with error [8] and aborts the same navigation requests.

Source

Thrown at crates/biome_lsp/src/handlers/navigation.rs:140

        let target_line_index = LineIndex::new(&content);
        to_proto::range(&target_line_index, *definition_range, position_encoding)?
    };

    Ok(Location {
        uri: target_uri,
        range: target_range,
    })
}

fn uri_from_path(path: &BiomePath) -> Result<Uri, LspError> {
    let url = url::Url::from_file_path(path.as_path()).map_err(|_| {
        LspError::from(anyhow::anyhow!(
            "failed to convert path to URL: {}",
            path.as_path()
        ))
    })?;
    Uri::from_str(url.as_str())
        .map_err(|err| LspError::from(anyhow::anyhow!("failed to convert URL to URI: {err}")))
}

View on GitHub (pinned to 7529811358)

Solutions

Inspect the failing file path (from the surrounding navigation request or logs) for unusual characters or escape sequences and rename/normalize the file.
Verify no tooling rewrote the path (e.g. shell escaping producing literal % sequences in the filename).
Report upstream to Biome with the exact path, since a URL produced by Url::from_file_path should always be parseable as a Uri.

Defensive patterns

Strategy: validation

Validate before calling

// Client-side: reject filenames that would need unusual escaping before the server ever sees them
function isSafeFileName(name) {
	return !/[%\u0000-\u001f]/.test(name); // avoid %-sequences and control chars in file names
}

if (!isSafeFileName(fileName)) {
	throw new Error(`rename ${fileName}: contains characters that break URI round-trips`);
}

Try / catch

try {
	const locations = await connection.sendRequest("textDocument/definition", params);
} catch (err) {
	if (String(err?.message ?? err).includes("failed to convert URL to URI")) {
		// exotic path encoding; skip navigation for this target rather than crashing
		return [];
	}
	throw err;
}

Prevention

Avoid literal percent signs and control characters in file names; they can produce encoding the Uri parser rejects.
Do not let tooling write shell-escaped strings into file names (e.g. literal %20 in a name).
If it reproduces, capture the exact path and report it upstream; server-generated file:// URLs should always parse as Uri.

When it happens

Trigger: A file path containing byte sequences that survive Url::from_file_path but fail Uri::from_str: exotic escape sequences, malformed percent-encoding introduced elsewhere, or non-standard path shapes on the platform.

Common situations: Rare; usually exotic filenames or a path-construction bug upstream. Normal spaces and unicode are percent-encoded by the url crate and parse fine.

Related errors

AI-assisted analysis of biomejs/biome@7529811358 (2026-08-16). Data as JSON: /api/errors/d8edb721728b28c2. Report an issue: GitHub.