# Handle Errors
URL: /runtime/guides/error-handling



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

## Prerequisites [#prerequisites]

Complete the [Quick Start](/runtime/getting-started/quick-start) and read the [Client API](/runtime/api/client) result shapes.

## Steps [#steps]

### 1. Inspect operation results [#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.

```typescript
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 [#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 [#3-handle-operational-rejection]

```typescript
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;
    }
  }
}
```

| Error                    | Code                        | Guard                      |
| ------------------------ | --------------------------- | -------------------------- |
| `OperationAbortedError`  | `RUNTIME_OPERATION_ABORTED` | `isOperationAbortedError`  |
| `OperationTimeoutError`  | `RUNTIME_OPERATION_TIMEOUT` | `isOperationTimeoutError`  |
| `RuntimeTerminatedError` | `RUNTIME_TERMINATED`        | `isRuntimeTerminatedError` |

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 [#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 [#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 [#related]

* [Core Types](/runtime/api/types)
* [Live Rendering](/runtime/guides/live-rendering)
* [Configure Render Timeouts](/runtime/guides/render-timeouts)
* [Render Lifecycle](/runtime/concepts/render-lifecycle)