ramensoftware/windhawk · error · std::runtime_error

Failed to start the global hooking session

Error message

Failed to start the global hooking session

What it means

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.

Solutions

1. Check Windhawk engine logs for the underlying failure inside GlobalHookSessionStart
2. Verify the installed engine module matches the app version; reinstall/repair Windhawk
3. Check antivirus/EDR software that may block global Windows hook installation
4. Ensure the process runs in an interactive desktop session where global hooks are allowed
5. Retry engine start after a reboot if hook resources were exhausted

Example fix

// before
EngineControl engineControl; // throws if session can't start
// after
std::unique_ptr<EngineControl> engineControl;
try {
    engineControl = std::make_unique<EngineControl>();
} catch (const std::exception& e) {
    Log(L"engine start failed: %hs", e.what());
}

try {
    EngineControl control;
} catch (const std::exception& e) {
    Log(L"EngineControl failed: %hs", e.what());
    // fall back to engine-less mode or retry
}

When it happens

Trigger: Constructing EngineControl when pGlobalHookSessionStart() returns NULL — e.g. the hook DLL failed to initialize its session internally.

Common situations: 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.

Related errors

• throw ResultException(failure)
• throw PortableSettingsException(error)
• ATL exception: HRESULT 0x
• Missing path value
• Missing RegistryKey value

AI-assisted analysis of ramensoftware/windhawk@61d99ed8e1 (2026-09-12). Data as JSON: /api/errors/d79f3e75545214f8. Report an issue: GitHub.

Appendix: source

Thrown at src/windhawk/app/engine_control.cpp:38

    THROW_LAST_ERROR_IF_NULL(pGlobalHookSessionStart);

    pGlobalHookSessionHandleNewProcesses =
        reinterpret_cast<GLOBAL_HOOK_SESSION_HANDLE_NEW_PROCESSES>(
            GetProcAddress(engineModule.get(),
                           "GlobalHookSessionHandleNewProcesses"));
    THROW_LAST_ERROR_IF_NULL(pGlobalHookSessionHandleNewProcesses);

    pHandleNewLogonSession = reinterpret_cast<HANDLE_NEW_LOGON_SESSION>(
        GetProcAddress(engineModule.get(), "HandleNewLogonSession"));
    THROW_LAST_ERROR_IF_NULL(pHandleNewLogonSession);

    pGlobalHookSessionEnd = reinterpret_cast<GLOBAL_HOOK_SESSION_END>(
        GetProcAddress(engineModule.get(), "GlobalHookSessionEnd"));
    THROW_LAST_ERROR_IF_NULL(pGlobalHookSessionEnd);

    hGlobalHookSession = pGlobalHookSessionStart();
    if (!hGlobalHookSession) {
        throw std::runtime_error("Failed to start the global hooking session");
    }
}

EngineControl::~EngineControl() {
    pGlobalHookSessionEnd(hGlobalHookSession);
}

BOOL EngineControl::HandleNewProcesses() {
    return pGlobalHookSessionHandleNewProcesses(hGlobalHookSession);
}

BOOL EngineControl::HandleNewLogonSession(DWORD sessionId) {
    return pHandleNewLogonSession(sessionId);
}

View on GitHub (pinned to 61d99ed8e1)