Error Handling

Error handling protects against data loss when a Micro-Integration successfully receives a message from the source but the message fails during processing or publishing. Error handling is optional and configured per workflow. Retry and Dead Message Queue (DMQ) are independent features that can be enabled in any combination; both are disabled by default.

Retry and DMQ are configured per workflow under solace.connector.workflows.<workflow-id> in your application.yml:

• Retry—When retry is enabled, the Micro-Integration retries a failed publish using exponential backoff. Each successive retry waits longer than the previous one, up to the configured maximum backoff interval.

• Workflow  DMQ—When the workflow DMQ is enabled, messages that cannot be processed or delivered are published to a designated queue on an event broker. This allows you to inspect, reprocess, or discard failed messages without losing them.

The workflow DMQ must be an existing queue on an event broker. The Micro-Integration does not create the queue.

This feature is intended for sources that lack built-in error handling, such as CDC and polling-based sources. If your source system has its own error handling mechanism, we recommend using that instead.

How Failed Messages Are Resolved

The Micro-Integration distinguishes between two categories of errors:

Processing errors

Errors that occur during message transformation, such as validation failures, type mismatches, or missing required fields. These errors are considered unrecoverable because retrying the same message would produce the same result.

If a processing error occurs, the Micro-Integration forwards the message directly to the workflow DMQ (if enabled) without any retry attempts. If the DMQ is not available (for example, it can't be reached or ingress is shut down) or is not configured, the Micro-Integration sends a NACK for the message.

Publishing errors

Errors that occur when the Micro-Integration is publishing the message to the target, such as network issues, rate limiting, or a temporarily unavailable target system. These errors may be transient.

If a publishing error occurs and retry is enabled, the Micro-Integration attempts to re-publish the message. When all retry attempts are exhausted (or if retry is not enabled), the Micro-Integration forwards the message to the workflow DMQ (if enabled). If the DMQ is not available (for example, it can't be reached or ingress is shut down) or is not configured, the Micro-Integration sends a NACK for the source message.

If your source system is an event broker, a queue-based system, or another system with built-in error handling, we recommend that you choose between using the source system's error handling or the workflow-level error handling—avoid enabling both at the same time.

Configuring Error Handling

For a detailed listing of configuration parameters for error handling, see Workflow Configuration Options.

For earlier versions of Micro-Integrations that use legacy transforms, you must enable transforms (transform.enabled: true) for any workflow where you want to enable retry or DMQ. If transforms are not enabled, the Micro-Integration will fail to start. If the documentation for your Micro-Integration doesn't include a Header and Payload Mapping Prior to Version X section, or your version is later than the one mentioned, your Micro-Integration doesn't use legacy transforms.

Retry Configuration Example

The following example enables retry for workflow 0, with a maximum of 5 retry attempts (6 total), starting with a 2-second delay that doubles each attempt up to a maximum of 30 seconds:

solace:
  connector:
    workflows:
      0:
        enabled: true
        retry:
          enabled: true
          max-attempts: 5
          back-off-initial-interval: 2000
          back-off-max-interval: 30000
          back-off-multiplier: 2.0

DMQ Configuration Example

The DMQ requires both a Spring Cloud Stream producer binding definition and a workflow-level configuration property.

The following example enables DMQ for workflow 0, which routes messages from MQTT to the event broker. In this example, the DMQ binding uses the same Solace binder as the workflow's data connections:

spring:
  cloud:
    stream:
      bindings:
        input-0:
          destination: <source-destination>
          binder: mqtt
        output-0:
          destination: <target-destination>
          binder: solace
        dmq-output-0:
          destination: <dmq-queue-name>
          binder: solace

solace:
  connector:
    workflows:
      0:
        enabled: true
        dead-message-queue:
          enabled: true
          binding: dmq-output-0