> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runanywhere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> SDKException, codes, and recovery

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

```ts theme={null}
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

```ts theme={null}
// 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:

```ts theme={null}
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:

```ts theme={null}
// 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

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

Rethrow what you did not recognise.