CatchBlock catch-block

When to Use

• Log errors to a database: Insert exception details into an error log table — type, message, stack trace, workflow ID, and the data being processed — for support teams and post-mortem analysis.
• Alert the team via Slack or email: Send an immediate alert when a critical integration fails, including the exception type and message so the on-call engineer can triage without opening the workflow editor.
• Graceful degradation with default values: If an enrichment API fails, set default values in the catch scope and let the main workflow continue — the user or downstream system receives a partial result rather than a workflow error.
• Create error tickets in Jira or Linear: Use an HttpRequest node in the catch scope to call a ticket API, pre-populating the ticket with exception details for the engineering backlog.
• Return a user-friendly error response: In customer-facing API workflows, the catch scope constructs a sanitised, human-readable error message instead of exposing internal exception details.

Configuration

Behavior Values

Output Ports

Exception Variables Written to Memory

When CatchBlock fires, the following variables are written into ExecutionMemory. Access them with $var.<name>:

With ErrorVariablePrefix: "payErr", the variables become:

OutputData Fields

The CatchBlock's own output data (accessible via $output.<catchNodeKey>):

Sample Output

Error Port — Exception Caught

{
  "error": {
    "errorCode": "HTTP_REQUEST_FAILED",
    "message": "Connection refused: upstream API at https://api.external.com/orders returned 503",
    "statusCode": 503,
    "nodeName": "fetchOrders",
    "nodeType": "HttpRequest",
    "timestamp": "2025-03-15T09:45:22.000Z"
  },
  "context": {
    "workflowId": "wf_order_sync",
    "executionId": "exec_20250315_001",
    "attemptNumber": 1
  }
}

Expression Reference

Validation Errors

Node Policies and GuardRails

• Never put CatchBlock outside TryBlock scope: CatchBlock is only valid when it follows a TryBlock. Placing it elsewhere produces a validation error and the workflow cannot be published.
• FinallyBlock must follow CatchBlock: If you have a FinallyBlock, it must come after the CatchBlock — not before. Execution order is always TryBlock scope → CatchBlock scope → FinallyBlock scope.
• Use Switch on exception type for smart routing: Connect a Switch node in the catch scope keyed on {{ $var.__exception_type__ }} to route different exception types to different handlers — retries for timeouts, alerts for auth errors, logging-only for validation errors.
• Use ErrorVariablePrefix for nested try/catch: When one TryBlock is nested inside another, set different prefixes on each CatchBlock to prevent the inner exception variables from overwriting the outer ones.
• Keep catch scope focused: Avoid putting complex business logic in the catch scope. The catch scope should: log the error, notify the team, set fallback values, and optionally trigger a retry. Complex logic belongs in the main workflow path after the try/catch/finally block.
• Don't expose stack traces to end users: Use __exception_message__ for user-facing messages and reserve __exception_stacktrace__ for internal error logs only.

Pattern Examples

Pattern 1 — Log Error and Continue

If an optional enrichment call fails, log it to the database and set a default value. The main workflow continues normally with the default value.

TryBlock  [key: "enrichTry"]
  └─► success ──► HttpRequest  [key: "enrichApi"]
                    GET /enrich/{{ $json.customerId }}
                    └─► VariableAssignment (creditScore = response.score)
CatchBlock  [key: "enrichCatch"]
  Behavior: continue
  └─► success ──► MongoDB  (insert into enrichment_errors:
                             { type: {{ $var.__exception_type__ }},
                               msg:  {{ $var.__exception_message__ }},
                               customerId: {{ $json.customerId }} })
                    └─► VariableAssignment (creditScore = -1)  (default)
FinallyBlock  [key: "enrichFinally"]
  └─► success ──► [use $var.creditScore — either real or default]

Pattern 2 — Type-Based Exception Routing

Route different exception types to different handlers using Switch on the exception type variable.

CatchBlock  [key: "apiCatch"]
  Behavior: continue
  └─► success ──► Switch  [key: "routeByError"]
                    Expression: {{ $var.__exception_type__ }}
                    Cases: {
                      "HttpRequestException": "handleNetworkError",
                      "UnauthorizedException": "handleAuthError",
                      "TimeoutException":      "handleTimeout"
                    }
                    DefaultPort: "handleUnknownError"
                    ├─► handleNetworkError ──► Delay (2s) ──► [retry]
                    ├─► handleAuthError    ──► EmailSmtp (alert: auth expired)
                    ├─► handleTimeout      ──► SlackNode (alert: API slow)
                    └─► handleUnknownError ──► MongoDB (log full stack trace)

Pattern 3 — Stop on Critical Failure with Notification

For unrecoverable failures (e.g., a core data write), stop the workflow after alerting the team. FinallyBlock still runs to update the status record.

CatchBlock  [key: "criticalCatch"]
  Behavior: stop
  └─► success ──► SlackNode  (#critical-alerts)
                    Message: "CRITICAL: {{ $var.__exception_type__ }} in OrderWrite
                              {{ $var.__exception_message__ }}
                              OrderId: {{ $json.orderId }}"
                    └─► MongoDB  (insert into failed_orders:
                                  { orderId, exceptionType, exceptionMsg, ts })
FinallyBlock  [key: "criticalFinally"]
  └─► success ──► MongoDB  (update orders SET status='failed'
                             WHERE id={{ $json.orderId }})