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.

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 event and also logged with console.warn.

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

classcatch (err) { if (err instanceof SDKError) … }

Usage

TypeScript

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

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

codepropertysince 1.0.0

readonly code: ErrorCodeValue

Machine-readable error code — one of the twenty ErrorCode values listed under Errors. Switch on it, with ErrorCode.X or the string.

Returns ErrorCodeValue

TypeScript

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

messagepropertysince 1.0.0

message: string

Human-readable, for logs, not users. Not stable API: never match on it. For a load failure shown in place, createLoadError puts plain language first and this message in a tooltip.

Returns string

fatalpropertysince 1.0.0

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.

Returns boolean

TypeScript

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

causepropertysince 1.0.0

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.

Returns unknown

namepropertysince 1.0.0

name: string

Always 'SDKError'.

Returns string