{"record":{"id":"d79f3e75545214f8","repo":"ramensoftware/windhawk","slug":"failed-to-start-the-global-hooking-session","errorCode":null,"errorMessage":"Failed to start the global hooking session","messagePattern":"Failed to start the global hooking session","errorType":"exception","errorClass":"std::runtime_error","httpStatus":null,"severity":"error","filePath":"src/windhawk/app/engine_control.cpp","lineNumber":38,"sourceCode":"    THROW_LAST_ERROR_IF_NULL(pGlobalHookSessionStart);\n\n    pGlobalHookSessionHandleNewProcesses =\n        reinterpret_cast<GLOBAL_HOOK_SESSION_HANDLE_NEW_PROCESSES>(\n            GetProcAddress(engineModule.get(),\n                           \"GlobalHookSessionHandleNewProcesses\"));\n    THROW_LAST_ERROR_IF_NULL(pGlobalHookSessionHandleNewProcesses);\n\n    pHandleNewLogonSession = reinterpret_cast<HANDLE_NEW_LOGON_SESSION>(\n        GetProcAddress(engineModule.get(), \"HandleNewLogonSession\"));\n    THROW_LAST_ERROR_IF_NULL(pHandleNewLogonSession);\n\n    pGlobalHookSessionEnd = reinterpret_cast<GLOBAL_HOOK_SESSION_END>(\n        GetProcAddress(engineModule.get(), \"GlobalHookSessionEnd\"));\n    THROW_LAST_ERROR_IF_NULL(pGlobalHookSessionEnd);\n\n    hGlobalHookSession = pGlobalHookSessionStart();\n    if (!hGlobalHookSession) {\n        throw std::runtime_error(\"Failed to start the global hooking session\");\n    }\n}\n\nEngineControl::~EngineControl() {\n    pGlobalHookSessionEnd(hGlobalHookSession);\n}\n\nBOOL EngineControl::HandleNewProcesses() {\n    return pGlobalHookSessionHandleNewProcesses(hGlobalHookSession);\n}\n\nBOOL EngineControl::HandleNewLogonSession(DWORD sessionId) {\n    return pHandleNewLogonSession(sessionId);\n}\n","sourceCodeStart":20,"sourceCodeEnd":53,"githubUrl":"https://github.com/ramensoftware/windhawk/blob/61d99ed8e182e1af1b60109612b6763ad1b4b74e/src/windhawk/app/engine_control.cpp#L20-L53","documentation":"EngineControl's constructor loads the engine module, resolves GlobalHookSessionStart, and calls it to open the global hooking session. If that call returns a null session handle, the constructor throws, meaning the windhawk engine could not establish its global hook infrastructure and engine-dependent operations cannot proceed.","triggerScenarios":"Constructing EngineControl when pGlobalHookSessionStart() returns NULL — e.g. the hook DLL failed to initialize its session internally.","commonSituations":"Corrupt or version-mismatched engine module; system-level hook exhaustion or security software blocking global hooks (WH_CBT/WH_GETMESSAGE) in the target session; running in environments (services, session 0) where global hooks cannot be established.","solutions":["Check Windhawk engine logs for the underlying failure inside GlobalHookSessionStart","Verify the installed engine module matches the app version; reinstall/repair Windhawk","Check antivirus/EDR software that may block global Windows hook installation","Ensure the process runs in an interactive desktop session where global hooks are allowed","Retry engine start after a reboot if hook resources were exhausted"],"exampleFix":"// before\nEngineControl engineControl; // throws if session can't start\n// after\nstd::unique_ptr<EngineControl> engineControl;\ntry {\n    engineControl = std::make_unique<EngineControl>();\n} catch (const std::exception& e) {\n    Log(L\"engine start failed: %hs\", e.what());\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    EngineControl control;\n} catch (const std::exception& e) {\n    Log(L\"EngineControl failed: %hs\", e.what());\n    // fall back to engine-less mode or retry\n}","preventionTips":["Keep the engine module and app versions matched","Whitelist Windhawk in antivirus/EDR that blocks global hooks","Only start the engine in an interactive desktop session","Handle stale engine processes before constructing EngineControl"],"tags":["windows","hooks","engine-startup","cpp"],"backgroundTag":"module-init-failed","analyzedSha":"61d99ed8e182e1af1b60109612b6763ad1b4b74e","analyzedAt":"2026-09-12T14:02:41.115Z","contentChangedAt":"2026-09-12T14:02:41.115Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}