# try_catch

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [cloud-data-platform-full.txt](https://docs.redpanda.com/cloud-data-platform-full.txt)

---
title: try_catch
latest-operator-version: v26.2.1
latest-console-tag: v3.10.0
latest-connect-version: 4.105.0
latest-redpanda-tag: v26.2.1
docname: connect/components/processors/try_catch
page-component-name: cloud-data-platform
page-version: master
page-component-version: master
page-component-title: Cloud
page-relative-src-path: connect/components/processors/try_catch.adoc
page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/develop/pages/connect/components/processors/try_catch.adoc
description: 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.
page-git-created-date: "2026-07-09"
page-git-modified-date: "2026-08-11"
---

<!-- Source: https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/try_catch.md -->

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`](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/try/) and [`catch`](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/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.

> 📝 **NOTE**
>
> Because the failure flag is cleared before the `catch` processors run, the [`error`](https://docs.redpanda.com/cloud-data-platform/develop/connect/guides/bloblang/functions/#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).

```yaml
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](https://docs.redpanda.com/cloud-data-platform/develop/connect/configuration/error_handling/).

#### Common

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

#### Advanced

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

## [](#fields)Fields

### [](#catch)`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**: `array<processor>`

**Default**: `[]`

### [](#error_metadata)`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)`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**: `array<processor>`

**Default**: `[]`