HoloBootError ​

Contract 2.0.0 · package sha256 a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e · generated from configurator-runtime.d.ts by services/onsite-scripter/scripts/build-contract-docs.mjs; edit the source, not this file.

Class · import { HoloBootError } from '@holostep-configurators/runtime-client'; · stable · since 2.0.0 · section 3. Errors

boot could not start the renderer. message is a plain sentence for reason that names no engine (R2-OUT-12), and cause the underlying error, for your own logs (undefined when nothing was thrown); branch on reason, never on either text. Without WebGL 2, boot rejects with it at once, before it creates anything or asks for a document. el's shadow root is left empty, and el can be booted again (BootOptions.el).

• 'no-webgl2': the browser has no WebGL 2 (iOS before 15, old or stripped browsers).
• 'webgl-context': WebGL 2 exists but the browser refused a context (a blocklisted GPU, hardware acceleration off, a headless browser without a GPU, too many live contexts), or lost it before the session's first frame (past the browser's live-context cap).
• 'disconnected': the page removed el while the session started (an el already out of the document at the call rejects HoloInputError instead, BootOptions.el).
• 'other': anything else, such as a runtime entry of another major that the bootstrap refused (spec section 5.1); cause holds what was thrown. One case is no retry: another configurator runtime on the page (a 1.x embed, or a runtime from another URL) defined the viewer element first, and message says so (BootOptions: one runtime per page). Invalid options still reject HoloInputError, and an aborted boot AbortError. When the runtime module itself fails to import (offline, or a browser that can't parse it), the import rejects before boot runs: there is no HoloBootError, and only a reload retries it.

Members ​

Declaration ​

export declare class HoloBootError extends Error {
  constructor(reason: HoloBootError['reason'], message?: string, options?: {
    cause?: unknown;
  });
  readonly name: 'HoloBootError';
  readonly reason: 'no-webgl2' | 'webgl-context' | 'disconnected' | 'other';
}

Example ​

Imports: values (has, validate, the Holo*Error classes, the pure helpers) from @holostep-configurators/runtime-client, types from @holostep-configurators/runtime-client/contract, /math and /testing names from those entries; boot from the runtime module the root's loadRuntimeAtFloor resolves to. A type your page defines is your app's: declare it there, never import it from the package.

Compiled under the contract's strict settings (examples/declaration/03-HoloBootError.ts):

import { HoloBootError, loadRuntimeAtFloor } from '@holostep-configurators/runtime-client';
import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare const el: HTMLElement;
declare const runtimeUrl: string;                      // src/config/runtime.ts: the compiled pin
declare function showAdvice(advice: 'update' | 'enable-3d' | 'retry'): void;
// The module that exports boot. It rejects, never with a HoloBootError, when the module
// fails to import or its contract is below your floor.
const runtime = await loadRuntimeAtFloor(runtimeUrl, {
  apiVersion: '2.0.0',                                 // src/runtime/REQUIRED_CONTRACT.json
  documentSchema: 'holo.viewer-document',
  documentVersion: 2,
});
try {
  await runtime.boot({ el, accountId: 120, contract: '2.0', signal });
} catch (error) {
  if (!(error instanceof HoloBootError)) throw error;
  if (error.reason === 'no-webgl2') showAdvice('update');
  else showAdvice(error.reason === 'webgl-context' ? 'enable-3d' : 'retry');
}

Generic-API test (spec 3.1) ​