ramensoftware/windhawk · critical

bridge not found

Error message

bridge not found: ${bridgePath}

What it means

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.

Solutions

1. Rebuild/reinstall the extension so the native bridge binary is included at the expected path
2. Check resolveBridgePath candidates and confirm which path it expects (log bridgePath) and place the binary there
3. Verify you installed the package matching your OS/architecture

Example fix

null

import fs from 'fs';
if (!fs.existsSync(expectedBridgePath)) {
  console.error(`native bridge missing at ${expectedBridgePath}`);
}

const bridgeExists = (p: string): boolean => fs.existsSync(p);

try { const bridge = loadBridgeFromDisk(); } catch (e) { if (e.message.startsWith('bridge not found')) showInstallRepairUi(e.message); else throw e; }

When it happens

Trigger: createWindhawkCore -> bridge() -> loadBridgeFromDisk when the packaged native bridge binary is absent from the install directory (broken build/publish, wrong platform binary shipped).

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

Related errors

• windhawk-core contract version mismatch: DLL has

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

Appendix: source

Thrown at src/windhawk-vscode/src/coreClient/dllBackend.ts:238

	return debugCoreBridgePath() ?? path.join(prebuildDir(), 'windhawk-core-bridge.node');
}

function resolveDllPath(appRoot: string): string {
	const override = debugCoreDllPath();
	if (override) {
		return override;
	}
	const candidates = [
		path.join(prebuildDir(), 'windhawk-core.dll'),
		path.join(appRoot, 'windhawk-core.dll'),
	];
	return candidates.find(p => fs.existsSync(p)) ?? candidates[0];
}

function loadBridgeFromDisk(): BridgeModule {
	const bridgePath = resolveBridgePath();
	if (!fs.existsSync(bridgePath)) {
		throw new Error(`bridge not found: ${bridgePath}`);
	}
	return nativeRequire(bridgePath) as BridgeModule;
}

// Load the bridge and the DLL and create the core session. Throws when
// either binary is missing or incompatible; the failure is fatal (there is no
// in-process fallback). `bridgeOverride` injects a fake bridge for tests (the
// production path loads the prebuilt .node from disk).
export function createDllBackend(options: DllBackendOptions, bridgeOverride?: BridgeModule): DllBackend {
	const { appRoot, windhawkVersion, userAgent, logger } = options;

	const bridge = bridgeOverride ?? loadBridgeFromDisk();

	// The bridge validates WhCoreGetAbiVersion itself; the contract version
	// is validated here, where the contract lives.
	const library = bridge.loadCore(resolveDllPath(appRoot));
	const info = JSON.parse(library.getInfoJson()) as { contractVersion: string };
	if (info.contractVersion !== CONTRACT_VERSION) {

View on GitHub (pinned to 61d99ed8e1)