linshenkx/prompt-optimizer · critical · InitializationError

ElectronImageUnderstandingServiceProxy can only be used in…

Error message

ElectronImageUnderstandingServiceProxy can only be used in Electron renderer process

What it means

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.

Solutions

1. Confirm you are inside the Electron renderer (window.electronAPI exists) before constructing the proxy.
2. Check BrowserWindow webPreferences.preload points at your compiled preload bundle that exposes electronAPI.imageUnderstanding via contextBridge.
3. In web contexts, use the non-Electron implementation/service instead of this proxy.

Example fix

// before
const svc = new ElectronImageUnderstandingServiceProxy() // in plain browser -> throws

// after
const svc = typeof window !== 'undefined' && (window as any).electronAPI?.imageUnderstanding
  ? new ElectronImageUnderstandingServiceProxy()
  : new ImageUnderstandingServiceImpl(/* deps */)

const hasBridge = typeof window !== 'undefined' &&
  Boolean((window as any).electronAPI?.imageUnderstanding)

const isElectronRenderer = (w: unknown): w is Window & { electronAPI: { imageUnderstanding: ElectronImageUnderstandingApi } } =>
  typeof w === 'object' && w !== null && 'electronAPI' in w

When it happens

Trigger: 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.

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

Related errors

• Electron API not available. Please ensure preload script is…
• GENERATION_FAILED
• CATEGORY_NOT_FOUND
• CONFIG_INVALID
• Core services initialization failed

AI-assisted analysis of linshenkx/prompt-optimizer@3e677b1d9f (2026-08-27). Data as JSON: /api/errors/5811fe52791362b7. Report an issue: GitHub.

Appendix: source

Thrown at packages/core/src/services/image-understanding/electron-proxy.ts:27

/**
 * Renderer-side bridge for image-understanding requests.
 *
 * Desktop networking must stay in the main process so it shares the same
 * proxy dispatcher and avoids renderer CORS restrictions.
 */
export class ElectronImageUnderstandingServiceProxy implements IImageUnderstandingService {
  private readonly api: ElectronImageUnderstandingApi

  constructor() {
    const electronApi = typeof window !== 'undefined'
      ? (window as unknown as {
          electronAPI?: { imageUnderstanding?: ElectronImageUnderstandingApi }
        }).electronAPI
      : undefined

    if (!electronApi?.imageUnderstanding) {
      throw new InitializationError(
        'ElectronImageUnderstandingServiceProxy can only be used in Electron renderer process',
      )
    }

    this.api = electronApi.imageUnderstanding
  }

  async understand(request: ImageUnderstandingExecutionRequest): Promise<LLMResponse> {
    return await this.api.understand(safeSerializeForIPC(request))
  }

  async understandStream(
    request: ImageUnderstandingExecutionRequest,
    callbacks: StreamHandlers,
  ): Promise<void> {
    try {
      const response = await this.understand(request)
      if (response.reasoning && callbacks.onReasoningToken) {

View on GitHub (pinned to 3e677b1d9f)