# Error Handling

> 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: Error Handling
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-connect-version: 4.93.0
latest-redpanda-tag: v26.1.9
docname: connect/configuration/error_handling
page-component-name: cloud-data-platform
page-version: master
page-component-version: master
page-component-title: Cloud
page-relative-src-path: connect/configuration/error_handling.adoc
page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/develop/pages/connect/configuration/error_handling.adoc
page-git-created-date: "2024-09-09"
page-git-modified-date: "2026-05-26"
---

<!-- Source: https://docs.redpanda.com/cloud-data-platform/develop/connect/configuration/error_handling.md -->

Redpanda Connect supports a range of [processors](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/about/), such as `http` and `aws_lambda`, that may fail when retry attempts are exhausted. When a processor fails, the message data continues through the pipeline mostly unchanged, except for the addition of a metadata flag, which you can use for handling errors.

This topic explains some common error-handling patterns, including dropping messages, recovering them with more processing, and routing them to a dead-letter queue. It also shows how to combine these approaches, where appropriate.

## [](#abandon-on-failure)Abandon on failure

You can use the [`try` processor](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/try/) to define a list of processors that are executed in sequence. If a processor fails for a particular message, that message skips the remaining processors.

For example:

-   If `processor_1` fails to process a message, that message skips `processor_2` and `processor_3`.

-   If a message is processed by `processor_1`, but `processor_2` fails, that message skips `processor_3`, and so on.


```yaml
pipeline:
  processors:
    - try:
      - resource: processor_1
      - resource: processor_2 # Skip if processor_1 fails
      - resource: processor_3 # Skip if processor_1 or processor_2 fails
```

## [](#recover-failed-messages)Recover failed messages

You can also route failed messages through defined processing steps using a [`catch` processor](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/catch/).

For example, if `processor_1` fails to process a message, it is rerouted to `processor_2`.

```yaml
pipeline:
  processors:
    - resource: processor_1 # Processor that might fail
    - catch:
      - resource: processor_2 # Processes rerouted messages
```

After messages complete all processing steps defined in the `catch` block, failure flags are removed and they are treated like regular messages.

To keep failure flags in messages, you can simulate a `catch` block using a [`switch` processor](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/switch/):

```yaml
pipeline:
  processors:
    - resource: processor_1 # Processor that might fail
    - switch:
      - check: errored()
        processors:
          - resource: processor_2 # Processes rerouted messages
```

## [](#logging-errors)Logging errors

When an error occurs, there may be useful information stored in the error flag. You can use [`error`](https://docs.redpanda.com/cloud-data-platform/develop/connect/guides/bloblang/functions/#error) Bloblang function interpolations to write this information to logs. You can also add the following Bloblang functions to expose additional details about the processor that triggered the error.

-   [`error_source_label`](https://docs.redpanda.com/cloud-data-platform/develop/connect/guides/bloblang/functions/#error_source_label)

-   [`error_source_name`](https://docs.redpanda.com/cloud-data-platform/develop/connect/guides/bloblang/functions/#error_source_name)

-   [`error_source_path`](https://docs.redpanda.com/cloud-data-platform/develop/connect/guides/bloblang/functions/#error_source_path)


For example, this configuration catches processor failures and writes the following information to logs:

-   The label of the processor (`${!error_source_label()}`) that failed

-   The cause of the failure (`${!error()}`)


```yaml
pipeline:
  processors:
    - try:
      - resource: processor_1 # Processor that might fail
      - resource: processor_2 # Processor that might fail
      - resource: processor_3 # Processor that might fail
    - catch:
      - log:
          message: "Processor ${!error_source_label()} failed due to: ${!error()}"
```

You could also add an error message to the message payload:

```yaml
pipeline:
  processors:
    - resource: processor_1 # Processor that might fail
    - resource: processor_2 # Processor that might fail
    - resource: processor_3 # Processor that might fail
    - catch:
      - mapping: |
          root = this
          root.meta.error = error()
```

## [](#attempt-until-success)Attempt until success

To process a particular message until it is successful, try using a [`retry`](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/retry/) processor:

```yaml
pipeline:
  processors:
    - retry:
        backoff:
          initial_interval: 1s
          max_interval: 5s
          max_elapsed_time: 30s
        processors:
          # Retries this processor until the message is processed, or the maximum elapsed time is reached.
          - resource: processor_1
```

## [](#drop-failed-messages)Drop failed messages

To filter out any failed messages from your pipeline, you can use a [`mapping` processor](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/mapping/):

```yaml
pipeline:
  processors:
    - mapping: root = if errored() { deleted() }
```

The mapping uses the error flag to identify any failed messages in a batch and drops the messages, which propagates acknowledgements (also known as "acks") upstream to the pipeline’s input.

## [](#reject-messages)Reject messages

Some inputs, such as `nats`, `gcp_pubsub`, and `amqp_1`, support nacking (rejecting) messages. Rather than delivering unprocessed messages to your output, you can use the [`reject_errored` output](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/outputs/reject_errored/) to perform a nack (or rejection) on them:

```yaml
output:
  reject_errored:
    resource: processor_1 # Only non-errored messages go here
```

## [](#route-to-a-dead-letter-queue)Route to a dead-letter queue

You can also route failed messages to a different output by nesting the [`reject_errored` output](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/outputs/reject_errored/) within a [`fallback` output](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/outputs/fallback/)

```yaml
output:
  fallback:
    - reject_errored:
        resource: processor_1 # Only non-errored messages go here
    - resource: processor_2 # Only errored messages, or delivery failures to processor_1, go here
```

If you want to route data differently based on the type of error message, you can use a [`switch` output](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/outputs/switch/):

```yaml
output:
  switch:
    cases:
      # Capture specifically cat-related errors
      - check: errored() && error().contains("meow")
        output:
          resource: processor_1

      # Capture all other errors
      - check: errored()
        output:
          resource: processor_2

      # Finally, route all successfully processed messages here
      - output:
          resource: processor_3
```

Finally, you can attach additional metadata when routing messages to the dead-letter queue, such as the error message. This can be done by running a series of [processors](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/processors/about/) before sending the data to the final [output](https://docs.redpanda.com/cloud-data-platform/develop/connect/components/outputs/about/).

```yaml
output:
  fallback:
    - reject_errored:
        resource: processor_1 # Only non-errored messages go here
    - processors:
        - mutation: |
            root.error = @fallback_error # Adds the error message before sending the message to the dead-letter queue output
      resource: processor_2 # Only errored messages, or delivery failures to processor_1, go here
```