{"record":{"id":"a38a4876bd7d6bd7","repo":"slackhq/nebula","slug":"coinitializeex-w","errorCode":null,"errorMessage":"CoInitializeEx: %w","messagePattern":"CoInitializeEx: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/network_category_windows.go","lineNumber":265,"sourceCode":"\n// coInit initializes COM for the current OS thread. The returned function must\n// be deferred to balance a successful init. RPC_E_CHANGED_MODE means COM is\n// already initialized in a different mode on this thread, which is still fine\n// for our calls but we must not Uninitialize in that case.\nfunc coInit() (func(), error) {\n\terr := windows.CoInitializeEx(0, windows.COINIT_MULTITHREADED)\n\tif err == nil {\n\t\treturn windows.CoUninitialize, nil\n\t}\n\tif e, ok := err.(syscall.Errno); ok {\n\t\tswitch uint32(e) {\n\t\tcase hrSFALSE:\n\t\t\treturn windows.CoUninitialize, nil\n\t\tcase hrRPCEChangedMode:\n\t\t\treturn func() {}, nil\n\t\t}\n\t}\n\treturn nil, fmt.Errorf(\"CoInitializeEx: %w\", err)\n}\n\nfunc createNetworkListManager() (*iNetworkListManager, error) {\n\tvar nlm *iNetworkListManager\n\tr1, _, _ := procCoCreateInstance.Call(\n\t\tuintptr(unsafe.Pointer(&clsidNetworkListManager)),\n\t\t0,\n\t\tuintptr(clsCtxAll),\n\t\tuintptr(unsafe.Pointer(&iidINetworkListManager)),\n\t\tuintptr(unsafe.Pointer(&nlm)),\n\t)\n\tif hr := hresult(r1); hr.failed() {\n\t\treturn nil, fmt.Errorf(\"CoCreateInstance(NetworkListManager): %s\", hr)\n\t}\n\treturn nlm, nil\n}\n\n// setNetworkCategory locates the network connection bound to adapterGUID and","sourceCodeStart":247,"sourceCodeEnd":283,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/network_category_windows.go#L247-L283","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before: initializing COM earlier on the same thread with a conflicting model\nruntime.LockOSThread()\nwindows.CoInitializeEx(0, windows.COINIT_MULTITHREADED) // host code pre-init\nsetNetworkCategory(guid, category)\n// after: let the library own COM init on the thread\nsetNetworkCategory(guid, category) // coInit handles CoInitializeEx itself","handlingStrategy":"try-catch","validationCode":"if runtime.GOOS != \"windows\" {\n    return fmt.Errorf(\"setNetworkCategory requires windows\")\n}","typeGuard":null,"tryCatchPattern":"if err := setNetworkCategory(guid, NetworkCategoryPrivate); err != nil {\n    var coErr *fmt.Errorf\n    if errors.As(err, &coErr) && strings.Contains(err.Error(), \"CoInitializeEx\") {\n        // run on a fresh OS thread / requeue after COM state settles\n    }\n    return fmt.Errorf(\"network category not set: %w\", err)\n}","preventionTips":["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"],"tags":["windows","com","network"],"backgroundTag":"com-initialization-failed","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}