# SDKError

The error the SDK throws and reports. It carries a machine-readable `code`, a human-readable `message`, and `fatal`. Switch on `code`; never match on `message`, which is not stable API. `ErrorCode` is exported as a frozen constant, and `ErrorCodeValue` is its union type, so you can exhaustively switch without hardcoding strings — every code is listed under [Errors](https://kernstra.com/docs/web-sdk/api/errors).

Errors reach you two ways. **Thrown** — anything you called directly that could not be done: `Kernstra.init()`, document loading, export, every method of the document API. Those all return promises, so the error arrives as a **rejection**: `await` the call in a `try`/`catch`; a promise-returning method never throws. **Reported** — failures inside the viewer's own async work (a page render, a print job, an action in Manage Pages), which have no call for you to catch: delivered on the viewer's [error](https://kernstra.com/docs/web-sdk/api/events#ev-error) event and also logged with `console.warn`.

`new SDKError(code, message, fatal = false)` is public, for test doubles.

- Kind: class
- Access: `catch (err) { if (err instanceof SDKError) … }`

## Usage

```ts
import { Kernstra, SDKError, ErrorCode } from '@kernstra/pdf-web-sdk';

try {
  await Kernstra.init({ license: import.meta.env.KERNSTRA_LICENSE });
} catch (err) {
  if (err instanceof SDKError) {
    // err.code is machine-readable; err.message is for logs, not users.
    if (err.code === ErrorCode.ENGINE_LOAD_FAILED) {
      showSetupHelp();
    }
    if (err.fatal) {
      teardownAndReinitialize();
    }
  }
}
```

## Constructor

```ts
new SDKError(code: ErrorCodeValue, message: string, fatal?: boolean, options?: { cause?: unknown })
```

Public, for test doubles. `err.name` is `'SDKError'`.

| Parameter | Type | Description |
| --- | --- | --- |
| `code` | `ErrorCodeValue` | One of the `ErrorCode` values. |
| `message` | `string` | For logs, not users. |
| `fatal?` | `boolean` | Whether the SDK itself is unusable after it. `false` when omitted. |
| `options?` | `{ cause?: unknown }` | `cause`: what was caught, when this wraps another error — the standard `Error.cause`. |

## Properties

### `code`

```ts
readonly code: ErrorCodeValue
```

Machine-readable error code — one of the twenty `ErrorCode` values listed under [Errors](https://kernstra.com/docs/web-sdk/api/errors). Switch on it, with `ErrorCode.X` or the string.

- Kind: property
- Since: 1.0.0

Returns `ErrorCodeValue`

```ts
if (err instanceof SDKError && err.code === 'PASSWORD_ERROR') {
  askForPassword();
}
```

Page: https://kernstra.com/docs/web-sdk/api/sdkerror/code

### `message`

```ts
message: string
```

Human-readable, for logs, not users. Not stable API: never match on it. For a load failure shown in place, [createLoadError](https://kernstra.com/docs/web-sdk/api/helpers/createloaderror) puts plain language first and this message in a tooltip.

- Kind: property
- Since: 1.0.0

Returns `string`

Page: https://kernstra.com/docs/web-sdk/api/sdkerror/message

### `fatal`

```ts
readonly fatal: boolean
```

`true` means the SDK itself is unusable: the engine failed to load (`ENGINE_LOAD_FAILED`) or the SDK stopped on an unrecoverable fault (`ENGINE_FAILED`), or `init()` was never called. Re-initialize, or stop. Everything else is `false` — the one operation failed and the SDK and the viewer are as they were: a page that did not render, a file that would not open (`CORS_ERROR`, `NETWORK_ERROR`, `FORMAT_ERROR`, `PASSWORD_ERROR`, `SECURITY_ERROR` — offer another file), an argument a call could not act on. `fatal` never says "the document is unusable"; the code does.

- Kind: property
- Since: 1.0.0

Returns `boolean`

```ts
viewer.on('error', ({ code, message, fatal }) => {
  if (fatal) showReloadPrompt();
});
```

Page: https://kernstra.com/docs/web-sdk/api/sdkerror/fatal

### `cause`

```ts
cause?: unknown
```

What was caught, when this wraps another error — the standard `Error.cause`, kept for a host's logs. `activateTool()` rejects with `UNKNOWN_ERROR` carrying the cause of a tool that could not start.

- Kind: property
- Since: 1.0.0

Returns `unknown`

Page: https://kernstra.com/docs/web-sdk/api/sdkerror/cause

### `name`

```ts
name: string
```

Always `'SDKError'`.

- Kind: property
- Since: 1.0.0

Returns `string`

Page: https://kernstra.com/docs/web-sdk/api/sdkerror/name

Web page: https://kernstra.com/docs/web-sdk/api/sdkerror