Error Handling

This guide covers the most common error-handling patterns: catching errors, choosing an error policy, and understanding when errors are thrown vs. returned. For complete field tables and the full list of error codes, see the Errors reference and ErrorPolicy reference.

Plexis uses a single error class — PlexisError — for all structural and runtime errors. Every error carries a code that identifies the specific failure.

PlexisError

PlexisError extends Error and adds structured metadata. See PlexisError for the complete field reference and the full list of error codes.

Catching Errors

For most applications, wrap follow() and run() in a try/catch:

import { PlexisError } from '@tde.io/plexis';

try {
  const result = await order.follow('submit');
} catch (err) {
  if (err instanceof PlexisError) {
    console.error(`[${err.code}] ${err.message}`);
    // err.domainId, err.pipelineId, err.nodeId, err.context are available
  }
}

ErrorPolicy

Both domains and pipelines accept an errorPolicy that controls what happens when a handler (action, guard, or lifecycle hook) throws an unexpected error:

See ErrorPolicy for the complete value reference.

Set the policy in the setup return:

const order = defineDomain('order', () => {
  // ...
  return { context: {}, initial: 'pending', errorPolicy: 'return' } as const;
});

Or via options (for pipeline):

const payment = definePipeline('payment', () => {
  // ...
  return { initial: 'validate' };
}, { errorPolicy: 'trace-and-return', tracer });

BUILDER_CLOSED

Registration helpers (when, on, node, fork, terminal) are only valid inside an active builder scope opened by defineDomain or definePipeline. Calling them outside throws PlexisError with code BUILDER_CLOSED:

import { when } from '@tde.io/plexis';

// Throws PlexisError: BUILDER_CLOSED
when('pending', () => {});

This safeguard prevents accidentally sharing registration calls across setup functions or calling helpers at module load time outside a setup context.