What causes "CoInitializeEx: %w" in slackhq/nebula?

Check the wrapped HRESULT (%w) to identify the specific CoInitializeEx failure code

CoInitializeEx: %w

Error message

CoInitializeEx: %w

What it means

This error wraps the failure of the Windows COM API CoInitializeEx, which must succeed before this library can talk to the Windows Network List Manager (NLM) to set a network adapter's category. coInit calls CoInitializeEx and if it returns anything other than S_OK, S_FALSE, or RPC_E_CHANGED_MODE, the HRESULT is wrapped and returned. It means the process could not initialize COM on the current thread, so NLM operations cannot proceed.

Source

Thrown at overlay/network_category_windows.go:265

// coInit initializes COM for the current OS thread. The returned function must
// be deferred to balance a successful init. RPC_E_CHANGED_MODE means COM is
// already initialized in a different mode on this thread, which is still fine
// for our calls but we must not Uninitialize in that case.
func coInit() (func(), error) {
	err := windows.CoInitializeEx(0, windows.COINIT_MULTITHREADED)
	if err == nil {
		return windows.CoUninitialize, nil
	}
	if e, ok := err.(syscall.Errno); ok {
		switch uint32(e) {
		case hrSFALSE:
			return windows.CoUninitialize, nil
		case hrRPCEChangedMode:
			return func() {}, nil
		}
	}
	return nil, fmt.Errorf("CoInitializeEx: %w", err)
}

func createNetworkListManager() (*iNetworkListManager, error) {
	var nlm *iNetworkListManager
	r1, _, _ := procCoCreateInstance.Call(
		uintptr(unsafe.Pointer(&clsidNetworkListManager)),
		0,
		uintptr(clsCtxAll),
		uintptr(unsafe.Pointer(&iidINetworkListManager)),
		uintptr(unsafe.Pointer(&nlm)),
	)
	if hr := hresult(r1); hr.failed() {
		return nil, fmt.Errorf("CoCreateInstance(NetworkListManager): %s", hr)
	}
	return nlm, nil
}

// setNetworkCategory locates the network connection bound to adapterGUID and

View on GitHub (pinned to dd8f660c0a)

Solutions

Check the wrapped HRESULT (%w) to identify the specific CoInitializeEx failure code
Ensure the calling thread has not pre-initialized COM with an incompatible model; let the library manage COM lifecycle or run the call on a thread with no prior CoInitialize call
Retry on a fresh thread/goroutine that has not initialized COM (RPC_E_CHANGED_MODE-style conflicts sometimes only surface as the generic path)
Repair the Windows COM installation (sfc /scannow) if the HRESULT indicates a system-level COM failure
Verify the code is running on a supported Windows version with the Network List Manager service available

Example fix

// before: initializing COM earlier on the same thread with a conflicting model
runtime.LockOSThread()
windows.CoInitializeEx(0, windows.COINIT_MULTITHREADED) // host code pre-init
setNetworkCategory(guid, category)
// after: let the library own COM init on the thread
setNetworkCategory(guid, category) // coInit handles CoInitializeEx itself

Defensive patterns

Strategy: try-catch

Validate before calling

if runtime.GOOS != "windows" {
    return fmt.Errorf("setNetworkCategory requires windows")
}

Try / catch

if err := setNetworkCategory(guid, NetworkCategoryPrivate); err != nil {
    var coErr *fmt.Errorf
    if errors.As(err, &coErr) && strings.Contains(err.Error(), "CoInitializeEx") {
        // run on a fresh OS thread / requeue after COM state settles
    }
    return fmt.Errorf("network category not set: %w", err)
}

Prevention

Do not call CoInitializeEx yourself on threads that will run this library
Pin the call to a dedicated OS thread (runtime.LockOSThread) with a clean COM state
Log the wrapped HRESULT for diagnosis
Only invoke on supported Windows versions with the netprofm service available

When it happens

Trigger: Calling setNetworkCategory (or Test_NLM_round_trip) on a Windows host where CoInitializeEx fails: COM was already initialized on the thread with an incompatible concurrency model and the special-case HRESULTs (S_FALSE, RPC_E_CHANGED_MODE) were not returned, COM is broken (e.g. corrupted system files), or running in an environment without a usable COM runtime (certain service/security-hardened contexts).

Common situations: Hosting the calling code inside a non-main thread that already initialized COM with STA when the library expects to handle its own init; embedding in a plugin/COM host application; running under minimal service accounts or sandboxes where COM initialization is restricted; Windows systems with damaged COM registrations.

Related errors

AI-assisted analysis of slackhq/nebula@dd8f660c0a (2026-09-03). Data as JSON: /api/errors/a38a4876bd7d6bd7. Report an issue: GitHub.