# `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`](boot.md) could not start the renderer. `message` is a plain sentence for [`reason`](HoloBootError.reason.md) that names no
engine (R2-OUT-12), and `cause` the underlying error, for your own logs (undefined when nothing
was thrown); branch on [`reason`](HoloBootError.reason.md), never on either text. Without WebGL 2, [`boot`](boot.md) 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`](BootOptions.el.md)).
- '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`](BootOptions.el.md)).
- '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`](BootOptions.md): 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`](boot.md) runs: there is no HoloBootError, and only a reload retries it.

## Members

| Member | Kind | Summary |
| --- | --- | --- |
| <a id="constructor"></a>[`constructor`](HoloBootError.constructor.md) | constructor | Public so app tests can build one to drive their failure state. |
| <a id="name"></a>[`name`](HoloBootError.name.md) | property | Always 'HoloBootError'. |
| <a id="reason"></a>[`reason`](HoloBootError.reason.md) | property | Why the renderer did not start. |

## Declaration

```ts
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`):

```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)

| Rule | Result |
| --- | --- |
| 1. Neutral name | pass: `HoloBootError` names no product |
| 2. A precedent | pass: [HTMLCanvasElement webglcontextcreationerror](https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/webglcontextcreationerror_event) (row `G49`) |
| 3. Two apps, or labs | pass: 28 apps (ledger: app-f9a32142f1, configurator-template; fleet cross-check: app-04c2774145, app-0c773a4ee3, app-37356bf09f, app-378d190f1b, app-4762caacdc, app-4f16d2f6da, app-4fd23bc869, app-510d750508 and 20 more) |
| 4. The cheaper fix first | decided per need in Appendix B: rows `G49` at tier stable (a member only where no rule, data, asset or app code serves the need) |