Connect

try_catch

Available in: Self-Managed

Executes a list of child processors on each message and, if any of them fail, executes a separate list of catch processors to recover from or react to the error.

This processor combines the behavior of the try and catch processors into a single block with an explicit recovery path. Because it contains both the fallible step and its recovery within a single processor, it is the recommended way to handle expected errors when strict error handling (error_handling.strict) is enabled.

Each message of a batch is processed individually. The processors field is executed with "try" semantics: as soon as a processor fails for a given message the remaining processors are skipped for that message.

Any message that failed is then routed to the catch processors. Before they run, the failure is moved off the message: it is stored as a structured object in a metadata field (see error_metadata, error by default) and the message’s failure flag is cleared. The error is therefore available to recovery logic as an ordinary variable rather than as a message property. The object contains:

  • what: the error message.

  • name: the name of the component that failed (when known).

  • label: the label of the component that failed (when set).

  • path: the dot-path of the component that failed (when known).

So a recovery mapping reads the failure with, for example, @error.what (equivalent to meta("error").what). Because the flag is cleared, the catch processors run under the normal error semantics, including strict, so a new failure raised while recovering is treated as a fresh error and is not silently tolerated.

Because the failure flag is cleared before the catch processors run, the error and error_source_* functions do not report the original failure within the catch block; use the metadata object instead. An empty or omitted catch simply records the error in metadata and clears the flag (the failure is swallowed). 
pipeline:
  processors:
    - try_catch:
        processors:
          - resource: foo
          - resource: bar
        catch:
          - mutation: 'root = "failed to process: " + @error.what'

In the example above, if either foo or bar fails for a message then the mutation is applied to that message, replacing its contents with a description of the error (read from the metadata object), and the message continues downstream without a failure flag.

More information about error handling can be found in Error Handling.

  • Common

  • Advanced

processors:
  label: ""
  try_catch:
    processors: []
    catch: []
    error_metadata: error
processors:
  label: ""
  try_catch:
    processors: []
    catch: []
    error_metadata: error

Fields

catch[]

A list of processors to execute on each message that failed one of the processors above. The message is no longer flagged as failed when these run; the error is available as an object in the metadata field named by error_metadata (e.g. @error.what). When omitted or empty the error is recorded in metadata and the flag is cleared (the failure is swallowed).

Type: processor

Default: []

error_metadata

The metadata key under which the caught error is stored, as an object with a what field (the error message) plus name, label and path fields describing the component that failed, before the catch processors are executed.

Type: string

Default: error

processors[]

A list of processors to execute on each message. If a processor fails for a given message the remaining processors in this list are skipped for that message, and the message is routed to the catch processors.

Type: processor

Default: []