swc-project/swc · critical

failed to create global mutex named `{}`: {}

Error message

failed to create global mutex named `{}`: {}

What it means

On Windows, swc_common synchronizes processes with a named global mutex created via CreateMutexA (for example to lock stdout/stderr across processes). If the OS returns a null handle, the code panics with the mutex name and io::Error::last_os_error(). This is an environment-level kernel-object allocation failure, not a logic error in user code.

Source

Thrown at crates/swc_common/src/errors/lock.rs:83

    impl Drop for Guard {
        fn drop(&mut self) {
            unsafe {
                ReleaseMutex((self.0).0);
            }
        }
    }

    let cname = CString::new(name).unwrap();
    unsafe {
        // Create a named mutex, with no security attributes and also not
        // acquired when we create it.
        //
        // This will silently create one if it doesn't already exist, or it'll
        // open up a handle to one if it already exists.
        let mutex = CreateMutexA(std::ptr::null_mut(), 0, cname.as_ptr() as *const u8);
        if mutex.is_null() {
            panic!(
                "failed to create global mutex named `{}`: {}",
                name,
                io::Error::last_os_error()
            );
        }
        let mutex = Handle(mutex);

        // Acquire the lock through `WaitForSingleObject`.
        //
        // A return value of `WAIT_OBJECT_0` means we successfully acquired it.
        //
        // A return value of `WAIT_ABANDONED` means that the previous holder of
        // the thread exited without calling `ReleaseMutex`. This can happen,
        // for example, when the compiler crashes or is interrupted via ctrl-c
        // or the like. In this case, however, we are still transferred
        // ownership of the lock so we continue.
        //
        // If an error happens.. well... that's surprising!

View on GitHub (pinned to 5176682b65)

Solutions

1. Retry the operation: transient resource exhaustion on Windows commonly clears after backoff
2. Reduce concurrent SWC processes on the machine to lower handle/memory pressure
3. Run the build outside the restricted sandbox or container that blocks named mutex creation
4. If persistent, capture the reported OS error code and report an issue with environment details

Example fix

// before
let _guard = swc_common::errors::lock(); // panics: failed to create global mutex

// after: treat as a transient OS failure with bounded retries
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::thread::sleep;
use std::time::Duration;
let guard = (0..3)
    .map(|_| catch_unwind(AssertUnwindSafe(swc_common::errors::lock)))
    .find_map(|g| match g {
        Ok(g) => Some(g),
        Err(_) => { sleep(Duration::from_millis(100)); None }
    });
assert!(guard.is_some(), "global mutex still failing after retries");

use std::panic::{catch_unwind, AssertUnwindSafe};
use std::{thread::sleep, time::Duration};
let mut guard = None;
for attempt in 0..3 {
    if let Ok(g) = catch_unwind(AssertUnwindSafe(swc_common::errors::lock)) {
        guard = Some(g);
        break;
    }
    sleep(Duration::from_millis(100 * (attempt + 1)));
}
if guard.is_none() { /* report OS resource exhaustion instead of crashing */ }

When it happens

Trigger: Running on Windows when CreateMutexA fails: exhausted handle quota or nonpaged memory, a sandbox/container restricting named-kernel-object creation, or a heavily loaded CI host. The mutex is created without security attributes and not pre-acquired, so only OS-level failures reach this branch.

Common situations: Windows CI runners under memory/handle pressure, test sandboxes and Windows containers that deny global kernel object namespaces, terminal multiplexers (mintty/conda) that alter the process environment, Wine-based environments.

Related errors

• Invalid attempt to iterate non-iterable instance. In order t
• Duplicated methods (${element.key}) can't be decorated.
• Decorators can't be placed on different accessors with for t
• Duplicated element (${element.key})
• Duplicated element (${elements[j].key})

AI-assisted analysis of swc-project/swc@5176682b65 (2026-08-17). Data as JSON: /api/errors/26f865d9c31a49da. Report an issue: GitHub.