Preserve Windows namespace module keys and UNC resolution errors

docs/runtime/nodejs-compat.mdx

@@ -123,6 +123,8 @@ We update this page regularly. It reflects the latest version of Bun's compatibi
 
 🟡 Missing `Module#load()`, `registerHooks`, `findPackageJSON`, `stripTypeScriptTypes`, `getSourceMapsSupport`/`setSourceMapsSupport`. Overriding `require.cache`, `require.extensions` and `module._resolveFilename` is supported. `syncBuiltinESMExports`, `module._load`, `module._pathCache` and `module.register` are no-ops (we recommend [`Bun.plugin`](/runtime/plugins) instead). `findSourceMap` always returns `undefined`.
 
+On Windows, CommonJS resolution preserves namespaced drive paths (`\\?\C:\`). As in Node.js, namespaced and ordinary drive paths have distinct module cache entries. Ordinary UNC paths work with `createRequire()`. File URLs work with `createRequire()` and `import()`. Direct namespaced UNC resolution preserves Node.js 24's root `lstat` error for existing modules; missing modules report `MODULE_NOT_FOUND`.
+
 ### [`node:net`](https://nodejs.org/api/net.html)
 
 🟢 Fully implemented, including `BlockList`, `SocketAddress`, `autoSelectFamily`, Unix domain sockets and `server.listen({ fd })`. `new net.Socket({ fd })` cannot read from an existing file descriptor (only write-only wrapping works). `server.listen(handle)` only accepts `{ fd }`. Missing `blockList.toJSON()`/`fromJSON()`.

src/js/builtins/CommonJS.ts

@@ -72,8 +72,18 @@ export function overridableRequire(this: JSCommonJSModule, originalId: string, o
 
   // A resolved id may carry a `?query` suffix (part of the module cache key);
   // match the native-addon extension against the path portion only.
-  // An addon that was compiled into an executable is a module of it, loaded like its other modules: the body of that module calls `process.dlopen`.
-  const queryIndex = id.indexOf("?");
+  // An addon compiled into an executable is loaded as a module whose body calls process.dlopen.
+  const queryIndex = id.indexOf(
+    "?",
+    process.platform === "win32" &&
+      id.length >= 4 &&
+      id[2] === "?" &&
+      (id[0] === "\\" || id[0] === "/") &&
+      (id[1] === "\\" || id[1] === "/") &&
+      (id[3] === "\\" || id[3] === "/")
+      ? 4
+      : 0,
+  );
   if ((queryIndex === -1 ? id.endsWith(".node") : id.endsWith(".node", queryIndex)) && !$isHiddenFromRequireCache(id)) {
     return $internalRequire(id, this, requireMap);
   }
@@ -193,7 +203,17 @@ export function internalRequire(id: string, parent: JSCommonJSModule, requireMap
   }
   // `id` keys the module cache and may carry a `?query` suffix;
   // `process.dlopen` needs the on-disk path.
-  const queryIndex = id.indexOf("?");
+  const queryIndex = id.indexOf(
+    "?",
+    process.platform === "win32" &&
+      id.length >= 4 &&
+      id[2] === "?" &&
+      (id[0] === "\\" || id[0] === "/") &&
+      (id[1] === "\\" || id[1] === "/") &&
+      (id[3] === "\\" || id[3] === "/")
+      ? 4
+      : 0,
+  );
   const filename = queryIndex === -1 ? id : id.substring(0, queryIndex);
   $assert(filename.endsWith(".node"));
 

src/jsc/VirtualMachine.rs

@@ -4330,12 +4330,9 @@ fn normalize_specifier_for_resolution<'a>(
     if bun_core::strings::has_prefix_comptime(specifier_, b"data:") {
         return specifier_;
     }
-    if let Some(i) = bun_core::strings::index_of_char_usize(specifier_, b'?') {
-        *query_string = &specifier_[i..];
-        &specifier_[..i]
-    } else {
-        specifier_
-    }
+    let path = crate::resolver_jsc::module_key_without_query(specifier_);
+    *query_string = &specifier_[path.len()..];
+    path
 }
 
 /// Heap-backed so only a pointer lives in TLS; see test/js/bun/binary/tls-segment-size.
@@ -5721,6 +5718,72 @@ impl VirtualMachine {
         }
     }
 
+    #[cfg(windows)]
+    fn namespaced_unc_resolution_error(
+        &mut self,
+        specifier: &[u8],
+        source: &[u8],
+        is_a_file_path: bool,
+    ) -> Option<bun_sys::Error> {
+        fn ordinary_unc_path(path: &[u8]) -> Option<Vec<u8>> {
+            if path.len() < 8
+                || !bun_paths::resolve_path::is_sep_any(path[0])
+                || !bun_paths::resolve_path::is_sep_any(path[1])
+                || path[2] != b'?'
+                || !bun_paths::resolve_path::is_sep_any(path[3])
+                || !path[4..7].eq_ignore_ascii_case(b"UNC")
+                || !bun_paths::resolve_path::is_sep_any(path[7])
+            {
+                return None;
+            }
+            let mut ordinary = b"\\\\".to_vec();
+            ordinary.extend_from_slice(&path[8..]);
+            Some(ordinary)
+        }
+
+        if self.transpiler.resolver.opts.preserve_symlinks {
+            return None;
+        }
+        let specifier = crate::resolver_jsc::module_key_without_query(specifier);
+        let ordinary_specifier = ordinary_unc_path(specifier);
+        let ordinary_source = ordinary_unc_path(source);
+        let namespace = if ordinary_specifier.is_some() {
+            specifier
+        } else if ordinary_source.is_some() {
+            source
+        } else {
+            return None;
+        };
+
+        // Only recover a realpath error after normal resolution failed. Resolve the
+        // ordinary UNC spelling to distinguish existing modules from missing ones,
+        // including extension and package-main lookup, without changing their keys.
+        let mut candidate = ResolveFunctionResult::default();
+        self._resolve(
+            &mut candidate,
+            ordinary_specifier.as_deref().unwrap_or(specifier),
+            ordinary_source.as_deref().unwrap_or(source),
+            false,
+            is_a_file_path,
+            bun_resolver::GlobalCache::disable,
+        )
+        .ok()?;
+        let mut candidate_path = candidate.path.to_vec();
+        candidate_path.push(0);
+        let stat = bun_sys::stat(bun_core::ZStr::from_slice_with_nul(&candidate_path)).ok()?;
+        if !bun_sys::is_regular_file(stat.st_mode as bun_sys::Mode) {
+            return None;
+        }
+
+        // Node's realpath traversal probes this partial namespace root, and its
+        // Windows error path omits the device prefix and trailing separator.
+        let mut root = *b"\\\\?\\UNC\\\0";
+        root[4..7].copy_from_slice(&namespace[4..7]);
+        bun_sys::lstat(bun_core::ZStr::from_slice_with_nul(&root))
+            .err()
+            .map(|err| err.with_path(&namespace[4..7]))
+    }
+
     /// Module-resolution core: resolves `specifier` relative to `source`, with
     /// path-length checks when `IS_A_FILE_PATH`. `Ok(Err(value))` is a
     /// resolution failure to be thrown/rejected with `value`.
@@ -5958,7 +6021,21 @@ impl VirtualMachine {
             IS_A_FILE_PATH,
             global_cache,
         );
-        if let Err(err) = resolve_result {
+        if let Err(err_) = resolve_result {
+            #[cfg(windows)]
+            if err_ == crate::CrateError::ModuleNotFound && !mode.is_esm() {
+                let message_count = log.msgs.len();
+                let unc_error = jsc_vm.namespaced_unc_resolution_error(
+                    specifier_utf8.slice(),
+                    normalize_source(source_utf8.slice()),
+                    IS_A_FILE_PATH,
+                );
+                log.msgs.truncate(message_count);
+                if let Some(err) = unc_error {
+                    return Ok(Err(crate::SysErrorJsc::to_js(&err, global)));
+                }
+            }
+            let err = err_;
             let import_kind = mode.import_kind();
             // Find a `.resolve`-metadata msg if the log has one.
             let resolve_msg_index = log
@@ -8357,10 +8434,7 @@ fn run_on_resolve(
     }
     // The importer's key ends in the query it was imported with.
     let importer = importer.to_utf8();
-    let importer = match bun_core::strings::index_of_char_usize(&importer, b'?') {
-        Some(query) => &importer[..query],
-        None => &importer[..],
-    };
+    let importer = crate::resolver_jsc::module_key_without_query(&importer);
     let importer = bun_core::StringView::borrow_utf8(importer);
     let _scope = OnResolveScope::enter(vm);
     let mut answer = None;

src/jsc/bindings/ImportMetaObject.cpp

@@ -222,8 +222,7 @@ static void throwIfResolvedFileIsRefused(JSC::JSGlobalObject* globalObject, JSC:
         JSC::AOT::willAnswerWithModule(globalObject, *module);
         return;
     }
-    size_t query = resolved.find('?');
-    StringView path = query == notFound ? StringView(resolved) : StringView(resolved).left(static_cast<unsigned>(query));
+    StringView path = StringView(resolved).left(moduleKeyPathLength(resolved));
     if (!path.endsWith(".node"_s) || Bun::letsTestRunLoadAddon(globalObject, resolved) || Bun::isFileInExecutable(resolved))
         return;
     if (JSValue error = Bun::errorIfCodeOutsideImageIsRefused(globalObject, Bun::ErrorCode::MODULE_NOT_FOUND, resolved))

src/jsc/bindings/PathInlines.h

@@ -52,6 +52,19 @@ ALWAYS_INLINE bool isAbsolutePath(WTF::String input)
 #endif
 }
 
+/// Length of the filesystem path in a legacy `<path>?query` module key.
+ALWAYS_INLINE unsigned moduleKeyPathLength(const WTF::String& key)
+{
+    unsigned devicePrefixLength = 0;
+#if OS(WINDOWS)
+    // `\\?\C:\...` and `\\.\...` are paths, not queries.
+    if (key.length() >= 4 && IS_SLASH(key[0]) && IS_SLASH(key[1]) && (key[2] == '?' || key[2] == '.') && IS_SLASH(key[3]))
+        devicePrefixLength = 4;
+#endif
+    size_t queryStart = key.find('?', devicePrefixLength);
+    return queryStart == WTF::notFound ? key.length() : static_cast<unsigned>(queryStart);
+}
+
 #undef IS_LETTER
 #undef IS_SLASH
 

src/jsc/resolver_jsc.rs

@@ -9,6 +9,25 @@ use bun_core::{String as BunString, strings};
 use bun_paths::resolve_path;
 use bun_paths::{Platform, SEP, SEP_STR};
 
+pub fn module_key_without_query(key: &[u8]) -> &[u8] {
+    // The question mark in a Windows device prefix is part of the path.
+    let start = if cfg!(windows)
+        && key.len() >= 4
+        && key[2] == b'?'
+        && resolve_path::is_sep_any(key[0])
+        && resolve_path::is_sep_any(key[1])
+        && resolve_path::is_sep_any(key[3])
+    {
+        4
+    } else {
+        0
+    };
+    match strings::index_of_char_usize(&key[start..], b'?') {
+        Some(index) => &key[..start + index],
+        None => key,
+    }
+}
+
 pub(crate) fn node_module_paths(path: &BunString) -> Vec<BunString> {
     crate::mark_binding!();
     node_module_paths_list(path, false)

src/runtime/jsc_hooks.rs

@@ -4073,12 +4073,9 @@ fn normalize_specifier_for_loader<'a>(
         slice = &slice[opath.len()..];
     }
     let specifier = slice;
-    let mut query: &[u8] = b"";
-    if let Some(i) = bun_core::strings::index_of_char_usize(slice, b'?') {
-        let i = i as usize;
-        query = &slice[i..];
-        slice = &slice[..i];
-    }
+    let path = bun_jsc::resolver_jsc::module_key_without_query(slice);
+    let query = &slice[path.len()..];
+    slice = path;
     (slice, specifier, query)
 }
 

test/js/bun/plugin/plugin-namespace-drive-letter.test.ts

@@ -4,7 +4,57 @@
 // drive, never a plugin namespace; resolving "C:\\..." with a one-letter
 // namespace registered must still reach the filesystem resolver.
 import { expect, test } from "bun:test";
-import { bunEnv, bunExe, tempDir } from "harness";
+import { bunEnv, bunExe, isWindows, tempDir } from "harness";
+import { join, toNamespacedPath } from "node:path";
+import { unsupported as aotUnsupported } from "../../../aot/supported";
+
+test.skipIf(!isWindows || !!aotUnsupported)(
+  "compiled executables refuse namespaced addons outside the image",
+  async () => {
+    using dir = tempDir("compiled-namespaced-addon", {
+      "addon.node": "native addon fixture",
+      "main.ts": `
+      const filename: string = process.argv[2];
+      try {
+        require(filename);
+        console.log("loaded");
+      } catch (error: any) {
+        console.log(error.code, error.message.includes("only runs code that was compiled into it"));
+      }
+    `,
+    });
+    const executable = join(String(dir), "app.exe");
+    await using build = Bun.spawn({
+      cmd: [bunExe(), "build", "--compile", "--aot", "main.ts", "--outfile", executable],
+      cwd: String(dir),
+      env: bunEnv,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [buildOut, buildError, buildExit] = await Promise.all([
+      build.stdout.text(),
+      build.stderr.text(),
+      build.exited,
+    ]);
+    expect({ buildOut: buildExit ? buildOut : "", buildError: buildExit ? buildError : "", buildExit }).toEqual({
+      buildOut: "",
+      buildError: "",
+      buildExit: 0,
+    });
+    const filename = toNamespacedPath(join(String(dir), "addon.node"));
+    for (const key of [filename, filename.replaceAll("\\", "/")]) {
+      await using proc = Bun.spawn({
+        cmd: [executable, key],
+        cwd: String(dir),
+        env: bunEnv,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]);
+      expect({ stdout, stderr, exitCode }).toEqual({ stdout: "MODULE_NOT_FOUND true\n", stderr: "", exitCode: 0 });
+    }
+  },
+);
 
 test("single-letter plugin namespace does not capture Windows drive paths", async () => {
   using dir = tempDir("plugin-ns-drive-letter", {
@@ -51,3 +101,42 @@ test("single-letter plugin namespace does not capture Windows drive paths", asyn
   expect(exitCode).toBe(0);
   void stderr;
 });
+
+test.skipIf(!isWindows)("Windows namespace prefixes survive plugin importer query stripping", async () => {
+  using dir = tempDir("plugin-device-prefix", {
+    "parent.cjs": 'module.exports = require("./namespace-child.js");',
+    "entry.cjs": `
+      const assert = require("node:assert/strict");
+      const { join, toNamespacedPath } = require("node:path");
+      const importers = [];
+      Bun.plugin({
+        name: "namespace-importers",
+        setup(build) {
+          build.onResolve({ filter: /namespace-child\\.js$/ }, ({ importer }) => {
+            importers.push(importer);
+            return { path: "child", namespace: "namespace-importers" };
+          });
+          build.onLoad({ filter: /.*/, namespace: "namespace-importers" }, () => ({
+            exports: { value: 42 }, loader: "object",
+          }));
+        },
+      });
+      const plain = join(process.cwd(), "parent.cjs");
+      const namespaced = toNamespacedPath(plain);
+      for (const key of [plain, plain + "?query", namespaced, namespaced + "?query"]) {
+        assert.equal(require(key).value, 42);
+      }
+      assert.deepEqual(importers, [plain, plain, namespaced, namespaced]);
+      console.log("ok");
+    `,
+  });
+
+  await using proc = Bun.spawn({
+    cmd: [bunExe(), "entry.cjs"],
+    env: bunEnv,
+    cwd: String(dir),
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([proc.stdout.text(), proc.stderr.text(), proc.exited]);
+  expect({ stdout, stderr, exitCode }).toEqual({ stdout: "ok\n", stderr: "", exitCode: 0 });
+});