Error handling

See Event direction for committed transaction sources and framework readiness events.

Stable failure envelope

Every consumer-visible initialization, datasource, renderer, export, persistence, snapshot, synchronization, collaboration, CSV, and XLSX failure is a SheetwriteError. Use code and operation for control flow; message is diagnostic text and may become more specific. context contains serialization-safe boundary details, retryable is present only when Sheetwrite can determine it, and cause retains the original exception in the current realm. toJSON() omits cause.

import { initSheetwrite, isSheetwriteError } from "@sheetwrite/core";
declare const wasmUrl: URL;
declare const correctedWasmUrl: URL;
declare function showInitializationError(message: string): void;


try {
  await initSheetwrite(wasmUrl);
} catch (error) {
  if (!isSheetwriteError(error) || error.code !== "initialization-failed") throw error;
  showInitializationError(error.message);
  // A failed source does not poison readiness. Retry with corrected input.
  await initSheetwrite(correctedWasmUrl);
}

The guard also recognizes validated cross-realm and serialized envelopes. A serialized envelope is structural; code that requires Error identity should construct or receive a live SheetwriteError.

declare function retryVisibleRows(request: {
  readonly sheet: string;
  readonly start: number;
  readonly end: number;
  readonly revision: number;
}): void;
declare function reportDegradedRendering(code: string): void;
declare function promptToEnableXlsx(): void;

grid.on("datasource-error", ({ request, error }) => {
  if (error.retryable !== false) {
    retryVisibleRows(request);
  }
});

grid.on("renderer-fallback", ({ error }) => {
  reportDegradedRendering(error.code);
  // Canvas rendering is already active; do not remount the Grid.
});

grid.on("export-error", ({ error }) => {
  if (error.code === "optional-backend-unavailable") {
    promptToEnableXlsx();
  }
});

Framework initialization callbacks and Grid operational events carry the same class identity exported by @sheetwrite/core and @sheetwrite/core/adapter. Normal mutation denials remain mutation-rejected results/events, and incomplete paged queries retain their explicit capability/result contracts; they are not converted into generic exceptions.

Typed error index

Start with SheetwriteError and isSheetwriteError. Branch on the stable code and operation fields; use the boundary-specific classes below only when their structured fields are needed.

The complete enums are SheetwriteErrorCode and SheetwriteErrorOperation; their runtime value sets are SHEETWRITE_ERROR_CODES and SHEETWRITE_ERROR_OPERATIONS.

Recovery by boundary

• SnapshotValidationError rejects malformed workbooks before partial hydration. Inspect its path-qualified errors; fix or reject the source instead of retrying unchanged bytes.
• SnapshotResourceError reports bounded workbook construction. Reduce the document or explicitly raise the named host-controlled ceiling.
• DelimitedTextOptionsError rejects an invalid CSV/TSV ceiling before work starts. Correct the option; retrying the same configuration cannot succeed.
• DelimitedTextResourceError and XlsxResourceError retain resource, limit, and actual. Reduce the input/output or explicitly change the applicable limit.
• IncompleteDataError identifies datasource pages required by the operation. Load those pages or use a visible-window operation; do not treat unloaded cells as empty.
• PersistenceError retains the host load/commit cause; its code distinguishes aborted work, invalid snapshots, resource limits, missing state, and rejected commits.
• IndexedDbPendingCommitStorageError distinguishes unavailable, blocked, aborted, corrupt, and quota-limited browser storage.
• SyncProtocolError rejects malformed or resource-violating remote input. Fix the producer; do not replay the same payload.
• SyncPendingCapacityError rejects a new local transaction before it can exceed the durable queue ceiling. Drain or reconcile pending work before retrying.

Worker startup and capability failures switch to the canvas renderer and emit renderer-fallback; observe grid.rendererKind to report the active renderer, not the requested option.

• GridEvents
• SnapshotValidationError
• IncompleteDataError
• SheetwriteError
• isSheetwriteError
• Framework lifecycle