toeverything/AFFiNE · error · Error

Electron preview handler "${String(name)}" is unavailable.

Error message

Electron preview handler "${String(name)}" is unavailable.

What it means

getRequiredDesktopHandler throws when the Electron preload API exposes no preview handlers object or lacks the requested handler (e.g. mermaid/typst), meaning the desktop bridge is missing or outdated relative to the renderer's expectations.

Source

Thrown at packages/frontend/core/src/modules/code-block-preview-renderer/platform-backend.desktop.ts:31

  ) => Promise<PreviewRenderResultMap['typst']>;
};

type DesktopPreviewApis = {
  preview?: DesktopPreviewHandlers;
};

function getDesktopPreviewHandlers() {
  const previewApis = apis as unknown as DesktopPreviewApis;
  return previewApis.preview ?? null;
}

function getRequiredDesktopHandler<Name extends keyof DesktopPreviewHandlers>(
  name: Name
): NonNullable<DesktopPreviewHandlers[Name]> {
  const handlers = getDesktopPreviewHandlers();
  const handler = handlers?.[name];
  if (!handler) {
    throw new Error(
      `Electron preview handler "${String(name)}" is unavailable.`
    );
  }
  return handler as NonNullable<DesktopPreviewHandlers[Name]>;
}

export async function renderMermaidSvgBackend(
  request: PreviewRenderRequestMap['mermaid']
): Promise<PreviewRenderResultMap['mermaid']> {
  if (!isMermaidWasmNativeRendererEnabled()) {
    return renderClassicMermaidSvg(request);
  }

  return getRequiredDesktopHandler('renderMermaidSvg')(request);
}

export async function renderTypstSvgBackend(
  request: PreviewRenderRequestMap['typst']

View on GitHub (pinned to b4c8548c09)

Solutions

1. Ensure the Electron preview handler is registered before rendering.
2. Update the desktop app if the handler is missing in this version.

When it happens

Trigger: Thrown when a code block preview render request (mermaid or typst) is executed in the Electron desktop app but the corresponding handler is missing from the exposed preview APIs on the desktop bridge.

Common situations: Occurs in the desktop client when the preload/IPC preview API is not injected or the app version lacks the requested handler; check that the desktop bridge exposes preview handlers and that app and frontend versions match.

AI-assisted analysis of toeverything/AFFiNE@b4c8548c09 (2026-08-18). Data as JSON: /api/errors/3a35484a4eda57a8. Report an issue: GitHub.