{"record":{"id":"9ca056be00d05aab","repo":"ramensoftware/windhawk","slug":"bridge-not-found-bridgepath","errorCode":null,"errorMessage":"bridge not found: ${bridgePath}","messagePattern":"bridge not found: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"src/windhawk-vscode/src/coreClient/dllBackend.ts","lineNumber":238,"sourceCode":"\treturn debugCoreBridgePath() ?? path.join(prebuildDir(), 'windhawk-core-bridge.node');\n}\n\nfunction resolveDllPath(appRoot: string): string {\n\tconst override = debugCoreDllPath();\n\tif (override) {\n\t\treturn override;\n\t}\n\tconst candidates = [\n\t\tpath.join(prebuildDir(), 'windhawk-core.dll'),\n\t\tpath.join(appRoot, 'windhawk-core.dll'),\n\t];\n\treturn candidates.find(p => fs.existsSync(p)) ?? candidates[0];\n}\n\nfunction loadBridgeFromDisk(): BridgeModule {\n\tconst bridgePath = resolveBridgePath();\n\tif (!fs.existsSync(bridgePath)) {\n\t\tthrow new Error(`bridge not found: ${bridgePath}`);\n\t}\n\treturn nativeRequire(bridgePath) as BridgeModule;\n}\n\n// Load the bridge and the DLL and create the core session. Throws when\n// either binary is missing or incompatible; the failure is fatal (there is no\n// in-process fallback). `bridgeOverride` injects a fake bridge for tests (the\n// production path loads the prebuilt .node from disk).\nexport function createDllBackend(options: DllBackendOptions, bridgeOverride?: BridgeModule): DllBackend {\n\tconst { appRoot, windhawkVersion, userAgent, logger } = options;\n\n\tconst bridge = bridgeOverride ?? loadBridgeFromDisk();\n\n\t// The bridge validates WhCoreGetAbiVersion itself; the contract version\n\t// is validated here, where the contract lives.\n\tconst library = bridge.loadCore(resolveDllPath(appRoot));\n\tconst info = JSON.parse(library.getInfoJson()) as { contractVersion: string };\n\tif (info.contractVersion !== CONTRACT_VERSION) {","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/ramensoftware/windhawk/blob/61d99ed8e182e1af1b60109612b6763ad1b4b74e/src/windhawk-vscode/src/coreClient/dllBackend.ts#L220-L256","documentation":"loadBridgeFromDisk() resolves the native bridge module path (resolveBridgePath picks the first existing candidate, falling back to candidates[0]) and throws when even that fallback does not exist on disk. The native bridge .node/.dll binding is mandatory — without it the VSCode extension cannot talk to windhawk-core.","triggerScenarios":"createWindhawkCore -> bridge() -> loadBridgeFromDisk when the packaged native bridge binary is absent from the install directory (broken build/publish, wrong platform binary shipped).","commonSituations":"VSIX built without the native binary, binary placed under an unexpected path after resolving candidates, platform mismatch (linux binary looked for on Windows), antivirus quarantined the file.","solutions":["Rebuild/reinstall the extension so the native bridge binary is included at the expected path","Check resolveBridgePath candidates and confirm which path it expects (log bridgePath) and place the binary there","Verify you installed the package matching your OS/architecture"],"exampleFix":"null","handlingStrategy":"fallback","validationCode":"import fs from 'fs';\nif (!fs.existsSync(expectedBridgePath)) {\n  console.error(`native bridge missing at ${expectedBridgePath}`);\n}","typeGuard":"const bridgeExists = (p: string): boolean => fs.existsSync(p);","tryCatchPattern":"try { const bridge = loadBridgeFromDisk(); } catch (e) { if (e.message.startsWith('bridge not found')) showInstallRepairUi(e.message); else throw e; }","preventionTips":["Verify the native binary ships in every packaged build (CI artifact check)","Confirm install layout matches resolveBridgePath candidates for your OS","Don't delete/quarantine the .node binary; re-add AV exclusions if needed"],"tags":["native","module","file-not-found"],"backgroundTag":"native-module-not-found","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"}