Error Handling

Everything the SDK throws is an SDKException, wrapping a proto-backed error so the same code and category cross every language binding.

import { SDKException } from '@runanywhere/electron'

try {
  const result = await RunAnywhere.llm.generate(prompt)
} catch (error) {
  if (error instanceof SDKException) {
    console.log(error.code, error.message)
  }
}

Codes worth handling

Code	Meaning	What to do
`notInitialized`	Called before `initialize()`	Initialize first
`modelNotFound`	No such model	Check the id, or register it
`networkUnavailable`	Download needs a connection	Retry when online
`insufficientStorage`	Not enough disk	Free space, or use `storage.deletePlan()`
`insufficientMemory`	The model will not fit	Unload something first
`microphonePermissionDenied`	No mic access	Send the user to System Settings
`timeout`	Took too long	Retry
`invalidApiKey`	Credentials rejected	Check the key
`cancelled`	The caller cancelled	Usually ignore
`invalidState`	Wrong order of operations	Read the message
`unsupportedCapability`	Not implemented in this build	See below

unsupportedCapability

// Throws: constrained decoding is not wired in
await RunAnywhere.llm.generateStructured(prompt, schema, 'constrained')

You will also meet it on win32-arm64, where only QHexRT loads and anything needing llama.cpp, ONNX, or Sherpa reports unavailable rather than failing obscurely at first use.

Errors in streams

Preflight failures throw from the call. A failure during generation arrives as a failed event:

for await (const event of RunAnywhere.llm.generateStream(prompt)) {
  if (event.type === 'failed') {
    showRetry(event.error)
    break
  }
  if (event.type === 'textDelta') output += event.text
}

Breaking out yields a cancelled terminal event, which is not a failure. This is the same shape as the Web SDK and the opposite of Swift, Kotlin, Flutter, and React Native, where in-flight failures are thrown into the consumer.

Errors across the context bridge

An exception thrown in the main process does not arrive in the renderer as an SDKException. Structured clone drops the prototype, so instanceof fails there. Send the code and message explicitly rather than the error object:

// main
catch (error) {
  if (error instanceof SDKException) {
    win.webContents.send('sdk-error', { code: error.code, message: error.message });
  }
}

Failures that are not the SDK

Symptom	Cause
Native module fails to load	`prebuilds/**` was not `asarUnpack`ed
”Corrupt model” on Windows ARM64	A missing `libqnnhtpv81.cat` beside the Hexagon skel
Window never appears	`ELECTRON_RUN_AS_NODE` is set
Nothing loads on Linux	No Linux build is published

The second one is worth remembering, because the error names the model rather than the packaging fault that caused it.

Reporting

catch (error) {
  if (error instanceof SDKException) {
    telemetry.track('sdk_error', { code: String(error.code) });
  } else {
    throw error;
  }
}

Rethrow what you did not recognise.

Getting Started

Swift SDK

Kotlin SDK

React Native SDK

Flutter SDK

Web SDK

Electron SDK

Vibe Coding

Codes worth handling

unsupportedCapability

Errors in streams

Errors across the context bridge

Failures that are not the SDK

Reporting

​Codes worth handling

​unsupportedCapability

​Errors in streams

​Errors across the context bridge

​Failures that are not the SDK

​Reporting

Codes worth handling

unsupportedCapability

Errors in streams

Errors across the context bridge

Failures that are not the SDK

Reporting