{"record":{"id":"ee13d04f6cc08cf8","repo":"ramensoftware/windhawk","slug":"internal-unknown-windhawk-core-error","errorCode":"INTERNAL","errorMessage":"unknown windhawk-core error","messagePattern":"unknown windhawk-core error","errorType":"exception","errorClass":"CoreDllError","httpStatus":null,"severity":"error","filePath":"src/windhawk-vscode/src/coreClient/dllBackend.ts","lineNumber":307,"sourceCode":"\t\t(opId, eventJson) => {\n\t\t\t// Deliver the event to its operation's handler (the dispatcher\n\t\t\t// deferred until the first async command landed).\n\t\t\t// An unknown id is a harmless no-op (a terminated operation).\n\t\t\topHandlers.get(opId)?.(JSON.parse(eventJson) as OperationEvent);\n\t\t},\n\t);\n\t// The session lives for the process: the WindhawkCore contract has no\n\t// dispose, and the bridge unrefs its callbacks (a leaked session cannot\n\t// keep the process alive) and tears the session down on GC/exit.\n\n\tasync function invoke<T>(command: string, params: unknown): Promise<T> {\n\t\tconst response = JSON.parse(await session.invoke(JSON.stringify({ command, params }))) as\n\t\t\t| { ok: true; result: T }\n\t\t\t| { ok: false; error?: { code?: string; message?: string; details?: unknown } };\n\t\tif (response.ok) {\n\t\t\treturn response.result;\n\t\t}\n\t\tthrow toCoreDllError(response.error);\n\t}\n\n\t// Start an async command and register its event handler. invokeAsync\n\t// returns the operation id (or throws the start-failure envelope); the\n\t// handler is keyed on that id. Returns the id so the caller can cancel.\n\tfunction startAsync(\n\t\tcommand: string,\n\t\tparams: unknown,\n\t\thandler: (event: OperationEvent) => void,\n\t): number {\n\t\tconst opId = session.invokeAsync(JSON.stringify({ command, params }));\n\t\topHandlers.set(opId, handler);\n\t\treturn opId;\n\t}\n\n\t// An async command that the contract exposes as a plain Promise (the\n\t// repository fetches, which emit no progress): resolve on completed,\n\t// reject on failed, and deregister on either.","sourceCodeStart":289,"sourceCodeEnd":325,"githubUrl":"https://github.com/ramensoftware/windhawk/blob/61d99ed8e182e1af1b60109612b6763ad1b4b74e/src/windhawk-vscode/src/coreClient/dllBackend.ts#L289-L325","documentation":"The VS Code extension's DLL backend invokes windhawk-core over a JSON command channel. When the core replies with an error envelope that has no usable code/message, toCoreDllError falls back to a generic INTERNAL error with message \"unknown windhawk-core error\". It signals the core rejected or failed the command without providing details.","triggerScenarios":"Calling any method on the DLL backend created by createDllBackend when the windhawk-core process returns {ok:false} with an error object lacking code/message, or the response cannot be mapped to a concrete error.","commonSituations":"windhawk-core crashed or returned a malformed error envelope; version mismatch between the extension and the core binary; an unimplemented command reached the core.","solutions":["Check that the windhawk-core binary version matches the extension (reinstall/repair Windhawk)","Capture the core's logs/stderr around the failing invoke to see the real cause","Retry the command; transient core-side failures (e.g. service not ready) may resolve","Report the missing error envelope to the Windhawk maintainers if it reproduces consistently"],"exampleFix":"// before: treating the thrown error as meaningful\nif (err.message === 'unknown windhawk-core error') { ... }\n// after: retry with backoff and surface core logs\ntry { await backend.getMods(); } catch (e) {\n  if (e.code === 'INTERNAL') { logCoreDiagnostics(); await retry(getMods); }\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":"function isCoreEnvelope(r: unknown): r is { ok: true; result: unknown } | { ok: false; error?: { code?: string; message?: string } } {\n  return typeof r === 'object' && r !== null && 'ok' in r;\n}","tryCatchPattern":"try {\n  const result = await backend.someCommand(params);\n} catch (e) {\n  if (e.code === 'INTERNAL' && /unknown windhawk-core error/.test(e.message)) {\n    logCoreDiagnostics();\n    await retryWithBackoff(() => backend.someCommand(params), 3);\n  } else { throw e; }\n}","preventionTips":["Keep the extension and windhawk-core versions in lockstep","Monitor core process liveness before invoking commands","Log raw envelopes on ok:false to preserve the real cause"],"tags":["ipc","typescript","internal-error"],"backgroundTag":"api-error-response","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"}