Handle Errors

Document/view operations distinguish model failures from operational rejection. Inspect structured issue codes and realm-safe error guards; messages are display text.

Prerequisites

Complete the Quick Start and read the Client API result shapes.

Steps

1. Inspect operation results

evaluation() and view rendering() return an outcome with superseded. Check it before narrowing the nested result with success. Document exports directly return ExportResult: success carries files, failure carries issues. Plugin hooks use KernelResult<T> with data; consumer document results have their own fields.

import type { RuntimeDocument } from '@taucad/runtime/client';

export async function inspectDocument(document: RuntimeDocument): Promise<void> {
  const outcome = await document.evaluation();
  if (outcome.superseded) {
    return;
  }
  for (const issue of outcome.evaluation.issues) {
    console.warn(issue.code, issue.severity, issue.message);
  }
  if (!outcome.evaluation.success) {
    return;
  }
  if (outcome.evaluation.views.length === 0) {
    console.log('This model offers no display view.');
  }
}

A successful result may still carry error-severity findings, warnings, or information. Treat it as clean only after checking all issues. Failed evaluations do not silently keep an older committed export source.

2. Use issue codes and locations

KernelIssue includes required message, code (KernelIssueCode), and severity; optional type, location (ErrorLocation), stack, stackFrames (KernelStackFrame[]), and details enrich diagnostics. Use locations for editor markers and codes for branching. Preserve the producer's issues even when another projection fails.

VIEW_UNKNOWN means the requested ID was never declared. VIEW_UNAVAILABLE means it is declared but not offered by this evaluation. Recovery should preserve the person's saved choice until they select a replacement.

3. Handle operational rejection

import {
  isOperationAbortedError,
  isOperationTimeoutError,
  isRuntimeTerminatedError,
  type RuntimeDocument,
} from '@taucad/runtime/client';

export async function evaluateSafely(document: RuntimeDocument): Promise<void> {
  try {
    await document.evaluation();
  } catch (error) {
    if (isOperationTimeoutError(error)) {
      console.warn(error.code, error.phase);
    } else if (isOperationAbortedError(error)) {
      console.warn(error.code);
    } else if (isRuntimeTerminatedError(error)) {
      console.warn('Recreate the client before retrying.');
    } else {
      throw error;
    }
  }
}

Transport loss rejects pending operations. A closed document/view read rejects; displaced update work can resolve as superseded. Noncooperative isolated work may terminate its host after a timeout. Explicitly retry using a fresh client; do not confuse termination with a requested document close.

4. Return structured kernel failures

Kernel authors return issues through the hook's KernelResult. Include a stable code, severity, producer identity where appropriate, and source location when known. Keep error extraction in the owning kernel; host code should not regex-match engine messages.

Variations

Retain the last successful picture while replacement work is pending or fails, but label its state. Clear stale artifacts after successful empty results. Subscribe to document and view status separately; global transport status cannot identify a pane's projection failure.

Related

• Core Types
• Live Rendering
• Configure Render Timeouts
• Render Lifecycle