Errors

All SDK errors derive from XViewerError. Catch the base class to handle anything thrown by the viewer, or branch on the subclass to react to specific failure categories.

Hierarchy

Error
└── XViewerError              category: "plugin" | "service" | "config" | "loader" | "renderer" | "component"
    ├── PluginError           category: "plugin"
    ├── ServiceError          category: "service"
    ├── ConfigError           category: "config"
    ├── LicenseError          category: "config"
    └── LoaderError           category: "loader"

XViewerError

class XViewerError extends Error {
  readonly code: string;
  readonly category: "plugin" | "service" | "config" | "loader" | "renderer" | "component";
}

Base class. Always carries a string code and a category. Catch this when you want a single handler for all SDK errors.

Subclasses

Class	Default code	Thrown when
PluginError	PLUGIN_ERROR	A plugin fails to register, activate, deactivate, or throws inside its lifecycle hooks.
ServiceError	SERVICE_ERROR	A service fails to start, a service method receives invalid state, or a required service is missing from the registry.
ConfigError	CONFIG_ERROR	XViewerConfig is malformed, a required field is missing, or a value fails validation at construction time.
LicenseError	LICENSE_ERROR	License key missing, malformed, signature invalid, expired, revoked, or feature/plugin not licensed. Categorized as "config".
LoaderError	LOADER_ERROR	Asset fetch fails, parsing fails, file type unsupported, or chunked manifest is invalid.

Usage

import {
  ViewerCore,
  XViewerError,
  ConfigError,
  LicenseError,
  LoaderError,
} from "@optellix/xviewr-sdk";

try {
  const viewer = new ViewerCore(container, config);
  await viewer.ready();
  const loader = viewer.getService("loader");
} catch (err) {
  if (err instanceof LicenseError) {
    console.error("License rejected:", err.code, err.message);
  } else if (err instanceof ConfigError) {
    console.error("Bad config:", err.code, err.message);
  } else if (err instanceof LoaderError) {
    console.error("Load failed:", err.code, err.message);
  } else if (err instanceof XViewerError) {
    console.error(`[${err.category}] ${err.code}: ${err.message}`);
  } else {
    throw err;
  }
}

Branch on instanceof for the subclass, on code for a specific failure mode within a category.

---

Confidential. Optellix Pvt. Ltd. proprietary documentation. Subject to applicable data-protection laws including DPDP 2023, GDPR, and CCPA.