Error Handling

MotionGPU normalizes all runtime errors into a consistent

Error normalization pipeline

All errors from initialization and per-frame rendering are processed by

The function inspects the error message, classifies it into a category, and produces a structured report.

MotionGPUErrorReport shape

interface MotionGPUErrorReport {
  title: string;
  message: string;
  hint: string;
  details: string[];
  stack: string[];
  rawMessage: string;
  phase: 'initialization' | 'render';
  source: {
    component: string;
    location: string;
    line: number;
    column?: number;
    snippet: Array<{
      number: number;
      code: string;
      highlight: boolean;
    }>;
  } | null;
}

interface MotionGPUErrorReport {
  title: string;
  message: string;
  hint: string;
  details: string[];
  stack: string[];
  rawMessage: string;
  phase: 'initialization' | 'render';
  source: {
    component: string;
    location: string;
    line: number;
    column?: number;
    snippet: Array<{
      number: number;
      code: string;
      highlight: boolean;
    }>;
  } | null;
}

This interface describes the runtime callback payload shape used by

Built-in classification patterns

The normalizer matches error messages against known patterns and assigns appropriate titles and hints:

Overlay behaviour

By default,

Key behaviours

• Even when
  showErrorOverlay
  is
  false
  ,
  onError
  is still called.
• With
  errorRenderer
  set and
  showErrorOverlay=true
  , custom UI is rendered instead of the default overlay.
• The default overlay renders above canvas content using a DOM portal.
• Multiple errors display the most recent one.

Minimal error handling

<FragCanvas
  {material}
  onError={(report) => {
    console.error(`[${report.phase}] ${report.title}: ${report.message}`);
    if (report.hint) console.info(`Hint: ${report.hint}`);
  }}
  showErrorOverlay={false}
/>

<FragCanvas
  {material}
  onError={(report) => {
    console.error(`[${report.phase}] ${report.title}: ${report.message}`);
    if (report.hint) console.info(`Hint: ${report.hint}`);
  }}
  showErrorOverlay={false}
/>

Custom error renderer

{#snippet myErrorRenderer(report)}
  <aside class="error-banner">
    <strong>{report.title}</strong>
    <p>{report.message}</p>
  </aside>
{/snippet}

<FragCanvas
  {material}
  errorRenderer={myErrorRenderer}
  onError={(report) => {
    console.error(report);
  }}
/>

{#snippet myErrorRenderer(report)}
  <aside class="error-banner">
    <strong>{report.title}</strong>
    <p>{report.message}</p>
  </aside>
{/snippet}

<FragCanvas
  {material}
  errorRenderer={myErrorRenderer}
  onError={(report) => {
    console.error(report);
  }}
/>

Shader compile diagnostics

When WGSL compilation fails, the renderer extracts diagnostics from

Source location mapping

The line map tracks which generated WGSL line corresponds to which original source:

Structured diagnostics payload

For WGSL compilation failures, the error carries a structured diagnostics payload:

interface ShaderCompilationDiagnostic {
  generatedLine: number;
  message: string;
  linePos?: number;
  lineLength?: number;
  sourceLocation: { kind: 'fragment' | 'include' | 'define'; line: number } | null;
}

interface ShaderCompilationDiagnostic {
  generatedLine: number;
  message: string;
  linePos?: number;
  lineLength?: number;
  sourceLocation: { kind: 'fragment' | 'include' | 'define'; line: number } | null;
}

interface ShaderCompilationDiagnosticsPayload {
  diagnostics: ShaderCompilationDiagnostic[];
  fragmentSource: string;
  includeSources: Record<string, string>;
  defineBlockSource?: string;
}

interface ShaderCompilationDiagnosticsPayload {
  diagnostics: ShaderCompilationDiagnostic[];
  fragmentSource: string;
  includeSources: Record<string, string>;
  defineBlockSource?: string;
}

• message
  — first compiler error enriched with source label and generated-line context (when available).
• details
  — additional compiler messages with the same contextual labels.
• source
  — component location, line number, and highlighted code snippet.

Overlay Source panel

When

• Active source tab: source label + location metadata (fragment/include/define), with optional column.
• Source snippet centred around the failing line
• Highlighted failing line
• Additional diagnostics in a collapsible section

Device loss and uncaptured errors

The renderer listens for two asynchronous error conditions:

Once captured, the error state is stored. The next render call throws a normalized error so

Retry strategy

When renderer creation fails,

Retry state resets when the pipeline signature changes (e.g., when you fix a shader error and hot-reload).

Production recommendations

1. Always provide
   onError
   — send reports to your logging/telemetry system.
2. Keep default overlay enabled in dev/staging — it surfaces WGSL errors with line-level precision.
3. Use
   errorRenderer
   in production when you need branded/error-system-integrated UI.
4. Surface
   phase
   and
   title
   prominently in alerting — they are the most actionable fields.
5. Use
   hint
   for contextual guidance — each error classification provides a specific suggestion.