{"record":{"id":"5811fe52791362b7","repo":"linshenkx/prompt-optimizer","slug":"electronimageunderstandingserviceproxy-can-only-be","errorCode":null,"errorMessage":"ElectronImageUnderstandingServiceProxy can only be used in Electron renderer process","messagePattern":"ElectronImageUnderstandingServiceProxy can only be used in Electron renderer process","errorType":"exception","errorClass":"InitializationError","httpStatus":null,"severity":"critical","filePath":"packages/core/src/services/image-understanding/electron-proxy.ts","lineNumber":27,"sourceCode":"\n/**\n * Renderer-side bridge for image-understanding requests.\n *\n * Desktop networking must stay in the main process so it shares the same\n * proxy dispatcher and avoids renderer CORS restrictions.\n */\nexport class ElectronImageUnderstandingServiceProxy implements IImageUnderstandingService {\n  private readonly api: ElectronImageUnderstandingApi\n\n  constructor() {\n    const electronApi = typeof window !== 'undefined'\n      ? (window as unknown as {\n          electronAPI?: { imageUnderstanding?: ElectronImageUnderstandingApi }\n        }).electronAPI\n      : undefined\n\n    if (!electronApi?.imageUnderstanding) {\n      throw new InitializationError(\n        'ElectronImageUnderstandingServiceProxy can only be used in Electron renderer process',\n      )\n    }\n\n    this.api = electronApi.imageUnderstanding\n  }\n\n  async understand(request: ImageUnderstandingExecutionRequest): Promise<LLMResponse> {\n    return await this.api.understand(safeSerializeForIPC(request))\n  }\n\n  async understandStream(\n    request: ImageUnderstandingExecutionRequest,\n    callbacks: StreamHandlers,\n  ): Promise<void> {\n    try {\n      const response = await this.understand(request)\n      if (response.reasoning && callbacks.onReasoningToken) {","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/linshenkx/prompt-optimizer/blob/3e677b1d9f7e0493c142c175560531e7ae786dce/packages/core/src/services/image-understanding/electron-proxy.ts#L9-L45","documentation":"Thrown by the ElectronImageUnderstandingServiceProxy constructor when window.electronAPI.imageUnderstanding is unavailable. The proxy is a thin bridge that forwards calls to the main process via contextBridge-exposed APIs, so it can only be instantiated in an Electron renderer where preload.js exposed electronAPI.imageUnderstanding.","triggerScenarios":"Instantiating the proxy in a plain browser tab or Node process; running in an Electron renderer whose preload script did not call contextBridge.exposeInMainWorld('electronAPI', { imageUnderstanding: ... }); sandboxed renderer without the preload attached.","commonSituations":"Running the app's web build (not the Electron build); preload script failing silently or being skipped due to a path misconfiguration in BrowserWindow webPreferences; new windows/webviews created without the preload.","solutions":["Confirm you are inside the Electron renderer (window.electronAPI exists) before constructing the proxy.","Check BrowserWindow webPreferences.preload points at your compiled preload bundle that exposes electronAPI.imageUnderstanding via contextBridge.","In web contexts, use the non-Electron implementation/service instead of this proxy."],"exampleFix":"// before\nconst svc = new ElectronImageUnderstandingServiceProxy() // in plain browser -> throws\n\n// after\nconst svc = typeof window !== 'undefined' && (window as any).electronAPI?.imageUnderstanding\n  ? new ElectronImageUnderstandingServiceProxy()\n  : new ImageUnderstandingServiceImpl(/* deps */)","handlingStrategy":"type-guard","validationCode":"const hasBridge = typeof window !== 'undefined' &&\n  Boolean((window as any).electronAPI?.imageUnderstanding)","typeGuard":"const isElectronRenderer = (w: unknown): w is Window & { electronAPI: { imageUnderstanding: ElectronImageUnderstandingApi } } =>\n  typeof w === 'object' && w !== null && 'electronAPI' in w","tryCatchPattern":null,"preventionTips":["Check window.electronAPI before constructing the proxy","Verify the preload script is attached to every BrowserWindow/webview"],"tags":["electron","initialization","environment"],"backgroundTag":"electron-preload-api-missing","analyzedSha":"3e677b1d9f7e0493c142c175560531e7ae786dce","analyzedAt":"2026-08-27T21:29:16.709Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}