Skip to content
Loopstack
Color theme

Error Handling Examples

Error handling workflow examples for the Loopstack automation framework.

One workflow per way a Loopstack workflow can react to a failing transition. Each example simulates the failure deterministically, so you can watch the mode work and copy the one you need. For the full decision tree (auto-retry → errorPlace → manual retry), see the Error Handling, Retry & Timeout guide.

Terminal window
npx giget@latest gh:loopstack-ai/loopstack/registry/examples/error-handling-examples src/error-handling-examples

Register the module:

import { Module } from '@nestjs/common';
import { LoopstackModule } from '@loopstack/loopstack-module';
import { ErrorHandlingExamplesModule } from './error-handling-examples/error-handling-examples.module';


@Module({
  imports: [LoopstackModule.forRoot(), ErrorHandlingExamplesModule],
})
export class AppModule {}

Install as a Dependency

Terminal window
npm install @loopstack/error-handling-examples
import { ErrorHandlingExamplesModule } from '@loopstack/error-handling-examples';

Environment

None — the examples call no LLM and need no secrets. The failures are simulated by two local tools: FlakyServiceTool (flaky_service) throws when told to, and SlowOperationTool (slow_operation) sleeps for a given time.

Examples

Example Studio title Description
Auto Retry Error Handling - Auto Retry Example retryAttempts re-runs a failed transition with exponential backoff
Retry Target Error Handling - Retry Target Example retryTarget routes each retry through a preparation place
Error Place Error Handling - Error Place Example errorPlace moves a failed workflow to a recovery place
Manual Retry Error Handling - Manual Retry Example The default: the workflow stays put and offers a Retry button
Transition Timeout Error Handling - Transition Timeout Example timeout fails a transition that runs too long
Sub-Workflow Error Place Error Handling - Sub-Workflow Error Place Example A failed child’s callback is routed to a recovery place via errorPlace

Auto Retry

@Transition({ to: 'end', retryAttempts: 2 }) — the service call fails on the first two attempts. The framework re-runs the transition after 1s and 2s, and the third attempt succeeds. The attempt number comes from ctx.execution.retryCount.

Terminal window
loopstack run auto_retry_example

Completes after about 3 seconds with result: { attempts: 3 }.

Files

  • workflows/auto-retry/auto-retry-example.workflow.ts

Retry Target

retryAttempts: 2, retryTarget: 'refresh_credentials' — each auto-retry re-enters the workflow at refresh_credentials instead of re-running the failed transition. That place does the preparation work (a simulated credential refresh) and loops back to ready, where the service call runs again.

Terminal window
loopstack run retry_target_example

Completes with result: { attempts: 3, refreshes: 2 }.

Files

  • workflows/retry-target/retry-target-example.workflow.ts

Error Place

errorPlace: 'service_failed' — the service call always fails, and the workflow moves to service_failed instead of staying at its place. The run shows as failed there, with a Recover button that triggers the recover wait transition and completes the run.

Terminal window
loopstack run error_place_example

The run ends failed at service_failed with Simulated external service error. Click Recover in Studio (Error Handling Examples → Error Handling - Error Place Example), or trigger it from the CLI — the run completes with result: { recovered: true }:

Terminal window
loopstack answer <run-id> --transition recover

Files

  • workflows/error-place/error-place-example.workflow.ts
  • workflows/error-place/error-place-example.ui.yaml — the Recover button

Manual Retry

No retryAttempts, no errorPlace — the default. The service call fails on the first attempt, and the workflow stays at its place with a Retry button next to the error. The second attempt succeeds.

Terminal window
loopstack run manual_retry_example

The run ends failed with Simulated external service error. Click Retry in Studio (in an interactive terminal, loopstack run offers the retry itself); the run completes with result: { attempts: 2 }.

Files

  • workflows/manual-retry/manual-retry-example.workflow.ts

Transition Timeout

timeout: 2000 — the first attempt runs a 5-second operation and is failed after 2 seconds. With no retry options, the timeout is handled like any other failure (manual retry). The second attempt finishes instantly.

SlowOperationTool passes ctx.signal to its sleep. The framework aborts that signal when the transition times out, so the abandoned operation stops instead of running on in the background — do the same in your own long-running tools.

Terminal window
loopstack run transition_timeout_example

The run ends failed with Transition 'runSlowOperation' timed out after 2000ms. Click Retry in Studio (or accept the retry loopstack run offers in an interactive terminal); the run completes with result: { attempts: 2 }.

Files

  • workflows/transition-timeout/transition-timeout-example.workflow.ts

Sub-Workflow Error Place

The parent starts a child workflow that always throws. Its callback transition declares errorPlace: 'child_failed', so the failed callback moves the parent to child_failed — the happy-path body of childCompleted never runs. A Recover button triggers the recover wait transition and completes the run.

Terminal window
loopstack run sub_workflow_error_place_example

The run ends failed at child_failed with Child workflow failed. Click Recover in Studio, or run loopstack answer <run-id> --transition recover — the run completes with result: { recovered: true }.

Files

  • workflows/sub-workflow-error-place/sub-workflow-error-place-example.workflow.ts
  • workflows/sub-workflow-error-place/sub-workflow-error-place-child.workflow.ts — the always-failing child
  • workflows/sub-workflow-error-place/sub-workflow-error-place-example.ui.yaml — the Recover button

About

Author: Jakob Klippel

License: MIT