Error Reference

StateMesh exports 16 typed error classes. Each has name, code, cause, metadata, and timestamp.

Error Classes

Class	Code	Used By
StateMeshError	STATEMESH_ERROR	Base class for all errors
ProviderError	STATEMESH_PROVIDER_ERROR	Missing or invalid StateMeshProvider
SelectorError	STATEMESH_SELECTOR_ERROR	Selector threw during evaluation
ComputedError	STATEMESH_COMPUTED_ERROR	Computed function threw
ActionError	STATEMESH_ACTION_ERROR	Action handler threw
DuplicateRegistrationError	STATEMESH_DUPLICATE_REGISTRATION	Duplicate action/transaction/computed/form name
TransactionError	STATEMESH_TRANSACTION_ERROR	Transaction failed (all retries exhausted)
TransactionRollbackError	STATEMESH_TRANSACTION_ROLLBACK_ERROR	Rollback handler threw
ResourceError	STATEMESH_RESOURCE_ERROR	Resource fetch failed
MutationError	STATEMESH_MUTATION_ERROR	Mutation failed
ApiClientError	STATEMESH_API_CLIENT_ERROR	API request failed (has status)
GuardError	STATEMESH_GUARD_ERROR	Operation blocked by guard
PersistenceError	STATEMESH_PERSISTENCE_ERROR	Persistence read/write failed
UrlStateError	STATEMESH_URL_STATE_ERROR	URL state serialization failed
FormError	STATEMESH_FORM_ERROR	Form validation or submission failed
SyncError	STATEMESH_SYNC_ERROR	Cross-tab sync failed

Error Properties

Property	Type	Description
name	string	Error class name
code	string	Machine-readable error code
message	string	Human-readable message
cause	Error | undefined	The original error
metadata	object	Context-specific data
timestamp	number	Date.now() when the error was created

Helper Functions

import {
  getErrorMessage,
  getErrorMetadata,
  getErrorStatus,
  isStateMeshError,
  isApiClientError
} from "statemesh-core";

// Safe message extraction
getErrorMessage(error);       // string

// Metadata extraction
getErrorMetadata(error);      // object

// HTTP status (ApiClientError only)
getErrorStatus(error);        // number | undefined

// Type guards
isStateMeshError(error);      // true if StateMeshError
isApiClientError(error);      // true if ApiClientError

Usage

import { TransactionError, ApiClientError, isApiClientError } from "statemesh-core";

try {
  await checkout.run();
} catch (error) {
  if (error instanceof TransactionError) {
    console.log(error.code);       // "STATEMESH_TRANSACTION_ERROR"
    console.log(error.metadata);   // { transaction: "cart.checkout", payload: ... }
    console.log(error.cause);      // Original error
  }
  if (isApiClientError(error)) {
    console.log(error.status);     // 401
  }
}

Important Notes

TIP

All errors extend StateMeshError, which extends Error. Use instanceof StateMeshError to catch any StateMesh error.

TIP

Error metadata includes context-specific data. TransactionError includes the transaction name and payload. ApiClientError includes the HTTP status and response headers.