(Windows) "The system cannot find the file specified. (os error 2)" when running `rustup doc` in a non-ANSI path

[SnipUndercover]

Verification

• I searched for recent similar issues at https://github.com/rust-lang/rustup/issues?q=is%3Aissue and found no duplicates.
• I am on the latest version of Rustup according to https://github.com/rust-lang/rustup/tags and am still able to reproduce my issue.

Problem

I installed rustup to learn the language. When running it standalone, I noticed the following remark:

If you are new to Rust consider running rustup doc --book to learn Rust.

I tried it out, however it did not work. Checking other commands I found that no rustup doc commands work...

Opening docs named `book` in your browser
error: couldn't open browser: IO error: The system cannot find the file specified. (os error 2)

Steps

1. Have a user with a non-ANSI character in their username (for example, ł)
2. Probably important: Change the locale encoding to UTF-8
   • Open the region control panel applet
     • Open the Run menu (Win+R)
     • Enter intl.cpl
     • Press Enter
   • Open the "Administrative" tab
   • Click "Change system locale..."
   • Check the "Beta: Use Unicode UTF-8 for worldwide language support" checkbox
   • Restart the PC
3. Download rustup-init and install rustup with default settings
4. Run rustup doc --book
5. Get really sad

Possible Solution(s)

The path seems to be URL-encoded as UTF-8 and passed to ShellExecuteW, which doesn't understand UTF-8; only UCS-2, or wchar_t.

Notes

Investigating events under Process Monitor, I found that the path rustup attempts to read is malformed. The expected path should contain Michał, not Micha�. (The \x82 byte is invisible under Process Monitor.)

I attempted to get rustup to spit out some logs, but $env:RUSTUP_LOG=trace did not produce anything useful. I then decided to clone rust-lang/rustup and poke around, getting it to spit out the path it's trying to access to see where the encoding mismatch happens.

I had absolutely no idea what I'm doing and the surrounding source code looked 😰, but I managed to determine that rustup URL-encodes the path and passes it to ShellExecuteW. I then found that my username was being URL-encoded in UTF-8, but ShellExecuteW does not understand UTF-8, only UCS-2.

I dumped the path being opened with this patch:

diff --git a/src/toolchain.rs b/src/toolchain.rs
index 57ed54a6..c2e7bd85 100644
--- a/src/toolchain.rs
+++ b/src/toolchain.rs
@@ -527,6 +527,7 @@ impl<'a> Toolchain<'a> {
             .ok()
             .with_context(|| anyhow!("invalid doc file absolute path `{}`", relative.display()))?;
         doc_url.set_fragment(fragment);
+        info!("opening path `{}`", doc_url.to_string());
         utils::open_browser(doc_url.to_string())
     }

This yielded the following:

info: opening docs named `book` in your browser
info: opening path `file:///C:/Users/Micha%C5%82/.rustup/toolchains/stable-x86_64-pc-windows-msvc/share/doc/rust/html/book/index.html`
error: couldn't open browser: IO error: The system cannot find the file specified. (os error 2)
error: process didn't exit successfully: `target\debug\rustup-init.exe doc --book` (exit code: 1)

I later tested this in a C# REPL and called ShellExecuteW with the ł being URL encoded and not. The URL-encoded version returned 2, which seems to be the Win32 error code for ERROR_FILE_NOT_FOUND. Running the non-URL-encoded version, it worked and returned 42.

Setting the $env:BROWSER variable to a valid browser executable seems to work, however.

Rustup version

rustup 1.29.0 (28d1352db 2026-03-05)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: the currently active `rustc` version is `rustc 1.98.0 (88d9e12ae 2026-08-18)`

Installed toolchains

Default host: x86_64-pc-windows-msvc
rustup home:  C:\Users\Michał\.rustup

installed toolchains
--------------------
stable-x86_64-pc-windows-msvc (active, default)

active toolchain
----------------
name: stable-x86_64-pc-windows-msvc
active because: it's the default toolchain
installed targets:
  x86_64-pc-windows-msvc

OS version

Windows 11, Version 25H2 (OS Build 26200.9168)

[ChrisDenton]

I later tested this in a C# REPL and called ShellExecuteW with the ł being URL encoded and not. The URL-encoded version returned 2, which seems to be the Win32 error code for ERROR_FILE_NOT_FOUND. Running the non-URL-encoded version, it worked and returned 42.

I believe this is the issue. This works with $BROWSER set because in that case we pass it as an argument to the browser rather than asking ShellExecuteW to look up the file.

I think this could be a windows bug. ShellExecuteW seems to work with single percent encodings like %20 but not for %C5%82 for some reason.

A workaround we could try is if the url fails to execute then retry with the literal path without urlencoding.

[rami3l]

I looked at our code regarding the OS-specific opening logic and confirmed that Rustup is doing nothing fishy here so I agree with @ChrisDenton that this is a Windows bug at least in terms of ShellExecuteW's implementation.

A workaround we could try is if the url fails to execute then retry with the literal path without urlencoding.

However URL-encoding is useful here at least because we are sometimes passing #fragment here so it is more convenient if the prefix has been properly encoded to avoid any ambiguous characters, so I am not sure if the semantics of this workaround is properly defined...

[ChrisDenton]

Yes, the cost would be that we lose the fragment part but I think that's better than not working at all.

The only other option I can think of is attempting to undo the percent-encoding for multibyte characters as I don't think the URL crate provides a way to not encode them.

[ChrisDenton]

This crate has more options: https://docs.rs/percent-encoding/2.3.2/percent_encoding/

EDIT: it has more options but not encoding non-ascii isn't one of them. Hm.

[ChrisDenton]

@rami3l do we have any test cases for fragment urls? I've been trying to find them without success but maybe I'm missing something.

Edit: ah we have lints::broken_intra_doc_links here but it only tests the path.

[rami3l]

@ChrisDenton Thanks for all the investigation!

I think I have been having a bad time finding any Windows documentation regarding what Windows is accepting here and what not as URLs... Once that is settled I think we can easily add a new test case if a potential fix strategy is identified by copying and modifying the test you have mentioned.

[ChrisDenton]

I think I have been having a bad time finding any Windows documentation regarding what Windows is accepting here and what not as URLs...

It's not documented at all. From my investigation ShellExecuteW always strips # fragment and only works with ascii percent encodings (but does work with non-ascii literal characters).

My thinking at the minute is that we should maybe bypass this entirely and try using FindExecutableW to find the actual browser .exe file then pass the url directly to that using Command.

[SnipUndercover]

I think this could be a windows bug. ShellExecuteW seems to work with single percent encodings like %20 but not for %C5%82 for some reason.

I looked at our code regarding the OS-specific opening logic and confirmed that Rustup is doing nothing fishy here so I agree with @ChrisDenton that this is a Windows bug at least in terms of ShellExecuteW's implementation.

That's more or less the conclusion I came to, but it's good to have confirmation. I'm not sure why it refuses to decode the URL as UTF-8 even when I have enabled the setting changing the encoding to UTF-8, instead falling back to what seems like ISO-8859-1. Certainly a Windows moment.

If a workaround gets implemented, I'd be happy to pull and test on my machine.

[ChrisDenton]

I created a bug report on opener repo. I'm uncertain if they want to support this case but if not then I can see about making a workaround in rustup.

[wuke32767]

according to my test, file:///R:/%B0%65.txt opens R:\°e.txt(U+00B0, U+0065), so i would say it is inventing UTF-16 Url Encoding, while there's no way to actually encode most of things (U+0100 or bigger)

[ChrisDenton]

Thanks for investigating! Yeah, I'm growing more convinced we should just avoid ShellExecuteW if possible. Or maybe only use it if we don't need to pass a url fragment (and therefore can use a regular file path).