What happens to messages in the dead letter queue?

Messages remain in the dead letter queue until you manually process them. You can redeliver them after fixing the underlying issue, forward them to a different channel, or discard them. The queue has a configurable retention period after which old messages are purged.

Can the agent notify users about delivery failures?

Yes. You can configure the agent to inform the user through an alternative channel when a message delivery fails. For example, if a file attachment fails to send, the agent can send a text message explaining the issue and suggesting a retry.

Do retries count against rate limits?

Yes. Retried messages count as new requests against your rate limits. This is why exponential backoff is important; it spaces out retries to avoid compounding a rate limit problem with additional retry traffic.

Troubleshooting

Message Delivery Failures: Retry Strategies

Ensure every message from your OpenClaw agent reaches its destination by implementing robust retry strategies and failure handling.

Deploy OpenClaw See How It Works

What You Will Get

By the end of this guide, your OpenClaw agent will handle message delivery failures gracefully by retrying intelligently, logging failures, and alerting you when manual intervention is needed. No message will be silently lost.

Message delivery can fail for many reasons: channel outages, network hiccups, invalid recipient addresses, or payload size limits. Each failure type requires a different handling strategy. A robust delivery system retries transient failures, reports permanent failures, and keeps a record of everything.

You will configure retry policies, set up dead letter queues for undeliverable messages, implement delivery confirmation, and monitor delivery health. The result is a messaging pipeline that handles failures transparently and keeps you informed.

Step-by-Step Setup

Follow these steps to implement reliable message delivery.

Review Delivery Failure Logs

Open your agent's logs and filter for delivery failures. Each failure entry includes the message ID, destination, error code, and timestamp. Categorize failures into transient (network issues, temporary outages) and permanent (invalid address, blocked recipient). This categorization determines the retry strategy.

Configure Retry Policies

Navigate to the Message Delivery settings and set up retry policies. For transient failures, configure three retries with exponential backoff starting at 2 seconds. For permanent failures, do not retry; instead, log the failure and alert the operator. Different channels can have different retry policies based on their reliability characteristics.

Enable Dead Letter Queues

Set up a dead letter queue for messages that fail after all retry attempts. The dead letter queue stores the full message content, recipient, and error details. You can review and manually redeliver these messages from the dashboard once the underlying issue is resolved.

Implement Delivery Confirmation

Enable delivery confirmation for channels that support read receipts or delivery acknowledgments. The agent's logs will show whether each message was delivered, read, or failed. This gives you visibility into the complete delivery lifecycle.

Set Up Payload Validation

Configure pre-send validation that checks message size, format, and content against the target channel's requirements. Messages that exceed the channel's payload limit should be split or truncated automatically rather than failing at delivery time.

Add Fallback Channels

For critical messages, configure a fallback channel. If delivery fails on the primary channel after all retries, the system automatically attempts delivery through the fallback. For example, if a WhatsApp message fails, the system can fall back to email.

Monitor Delivery Health

Set up a delivery health dashboard that shows the delivery success rate, average retry count, and dead letter queue size. Configure alerts for when the delivery failure rate exceeds a threshold, such as 5% of messages. Regular monitoring helps you catch systemic issues early.

Tips and Best Practices

Distinguish Transient from Permanent Failures

Retrying permanent failures wastes resources and delays alerts. Use error codes to classify failures accurately. Network timeouts are transient; invalid recipient addresses are permanent.

Set Maximum Retry Windows

Define a maximum time window for retries, like 1 hour. After this window, move the message to the dead letter queue regardless of retry count. Stale messages are often irrelevant by the time they would be delivered.

Review Dead Letter Queue Weekly

Check the dead letter queue at least once a week. Messages sitting there for more than a few days are likely outdated. Process or discard them to keep the queue manageable.

Test Failure Scenarios

Periodically simulate delivery failures to verify that your retry policies and fallback channels work correctly. A system that is never tested is a system that fails when you need it most.

Frequently Asked Questions

Channel Reconnection Rate Limit Troubleshooting Log Analysis and Debugging

Ready to get started?

Deploy your own OpenClaw instance in under 60 seconds. No VPS, no Docker, no SSH. Just your personal AI assistant, ready to work.

Deploy OpenClaw View Pricing

Starting at $24.50/mo. Everything included. 3-day money-back guarantee.