Skip to content

RabbitMQ (AMQP 1.0) Inbound Endpoint Reference

This reference page documents all the configuration parameters supported by the RabbitMQ Inbound Endpoint. These parameters control how the inbound endpoint connects to the RabbitMQ server, what queues it consumes from, the consumer type, message acknowledgment modes, and more. Use this table as a guide when configuring your inbound endpoint to ensure seamless and reliable integration with RabbitMQ.

Parameter Name Display Name Description Required Default Value
Generic
name Event Integration Name A unique name for this RabbitMQ Inbound Endpoint configuration. Yes -
sequence Injecting Sequence Name The name of the mediation sequence that will process the consumed RabbitMQ messages. Yes -
onError Error Sequence Name The name of the error handling sequence to execute if an error occurs during message consumption or processing. Yes -
suspend Suspend Inbound Suspend the inbound endpoint No false
Inbound Functional
sequential Execute sequentially If enabled, messages will be processed one after the other within the injection sequence, preserving message order. No true
coordination Coordination In a clustered environment, set this to true to ensure that only a single worker node is consuming messages from the queue at any given time. No true
Basic
rabbitmq.server.host.name Server Hosts Specifies the RabbitMQ server hostname(s) or IP address(es) for client connection. For high availability deployments, provide multiple hosts as a comma-separated list (e.g., rabbitmq1.example.com,rabbitmq2.example.com,rabbitmq3.example.com).

Single server configuration:
  • Hostname: rabbitmq.example.com - Recommended for production (enables DNS-based failover)
  • IP address: 192.168.1.100 - Direct IP connection (bypasses DNS resolution)
  • localhost: localhost or 127.0.0.1 - For local development and testing only
Multi-server configuration (High Availability):
  • Provide comma-separated list: rabbitmq1.example.com,rabbitmq2.example.com,rabbitmq3.example.com
  • Client automatically attempts connection to each host in sequence until successful
  • Enables automatic failover if the primary broker becomes unavailable
  • All hosts should be part of the same RabbitMQ cluster for proper operation
  • Order matters: hosts are tried in the specified order during connection and reconnection attempts
Best practices:
  • Use hostnames over IPs: Allows infrastructure changes without client reconfiguration
  • List all cluster nodes: Maximizes availability - if one node fails, client can connect to others
  • Geographic considerations: List closest/lowest-latency nodes first for optimal performance
  • Load balancer option: Can use a single load balancer hostname (e.g., rabbitmq-lb.example.com) instead of listing individual nodes, but this creates a single point of failure if the load balancer fails
  • Network segmentation: Ensure all listed hosts are accessible from the client's network segment
Port alignment: If providing multiple hosts, ensure corresponding ports are listed in rabbitmq.server.port in the same order. If only one port is specified, it applies to all hosts.

Connection behavior:
  • Client attempts connection to the first host in the list
  • If connection fails, automatically tries the next host
  • Continues through the list until a connection succeeds or all hosts are exhausted
  • After successful connection, if that connection drops, the client retries using the same failover logic
Important: This is a required parameter. For production deployments, always specify multiple hosts for high availability unless using a highly available load balancer.
Yes localhost
rabbitmq.server.port Server Ports Specifies the RabbitMQ server ports as a comma-separated list (e.g., port1,port2). Default is 5672 for non-SSL. Yes 5672
rabbitmq.queue.name Queue Name The name of the RabbitMQ queue to consume messages from. Yes -
rabbitmq.queue.type Type Specifies the type of RabbitMQ queue to interact with.
Options:
  • CLASSIC: The traditional RabbitMQ queue type with support for all messaging patterns and features. Offers flexibility and full protocol compatibility but provides limited fault tolerance as queues are stored on a single node. Suitable for development, testing, or non-critical workloads where high availability is not required.
  • QUORUM: A replicated queue type built on the Raft consensus algorithm, providing high availability and data safety through replication across multiple cluster nodes. Automatically handles leader election and failover. Designed for critical workloads requiring message durability and resilience against node failures. Recommended for production environments where message loss is unacceptable. Note: Does not support all classic queue features (e.g., priority queues, message TTL at message level).
  • STREAM: A persistent, append-only log structure optimized for high-throughput, large-volume message flows with non-destructive consumption. Messages are retained on disk and can be consumed multiple times by different consumers from any offset. Ideal for event streaming, audit logs, time-series data, and scenarios requiring message replay or long-term retention. Requires RabbitMQ 3.9+ and uses a different consumption model than traditional queues.
Yes QUORUM
rabbitmq.queue.auto.declare Auto Declare If enabled, the inbound endpoint will attempt to declare the queue if it doesn't exist. No true
rabbitmq.exchange.name Exchange Name Name of the exchange to bind the queue to. Leave empty to consume directly from the queue. No -
rabbitmq.exchange.type Type Defines how the exchange routes messages to queues based on routing rules.
Options:
  • DIRECT: Routes messages to queues based on an exact match between the routing key and the binding key. Simple and efficient for point-to-point messaging where each message should be delivered to specific queues. Ideal for task distribution and targeted message delivery scenarios.
  • FANOUT: Broadcasts all messages to all bound queues, ignoring routing keys entirely. Every queue bound to the exchange receives a copy of each message. Perfect for publish-subscribe patterns, notifications, and scenarios where the same message needs to reach multiple independent consumers simultaneously.
  • TOPIC: Routes messages based on wildcard pattern matching between the routing key and binding patterns. Binding keys can use wildcards: (matches exactly one word) and # (matches zero or more words). Enables flexible, hierarchical routing based on multi-part routing keys (e.g., stock.usa.tech). Suitable for complex routing scenarios like log aggregation, multi-criteria filtering, and selective subscription patterns.
  • HEADERS: Routes messages based on matching message header attributes rather than routing keys. Uses the x-match binding argument to specify whether all headers must match or any header match is sufficient. Provides the most flexible routing but with higher overhead. Best for complex routing rules based on multiple message properties or when routing logic cannot be expressed through routing keys alone.
No DIRECT
rabbitmq.exchange.auto.declare Auto Declare If enabled, the inbound endpoint will attempt to declare the exchange if it doesn't exist. No true
rabbitmq.routing.key Routing Key Routing key for binding the queue to a DIRECT or TOPIC exchange. Queue name is used if omitted. No -
User Authentication
rabbitmq.connection.sasl.mechanism SASL Mechanism Defines the SASL mechanism to use for connection authentication.
Possible values:
  • PLAIN: The default, standard authentication method that transmits username and password credentials in plain text. This mechanism is simple and widely supported but requires secure transport (TLS/SSL) to protect credentials during transmission. When OAuth2 authentication is enabled, the SASL mechanism should be set to PLAIN, as the OAuth2 token is passed as the password field.
  • EXTERNAL: Delegates authentication to an external mechanism, bypassing RabbitMQ's internal user database. This typically works in conjunction with the rabbitmq_auth_backend_external plugin or certificate-based authentication (TLS/SSL mutual authentication). Common use cases:
    • Client Certificate Authentication: The client's identity is extracted from the TLS certificate's Distinguished Name (DN) during the TLS handshake, eliminating the need for username/password credentials.
    • External Authentication Scripts: When using rabbitmq_auth_backend_external, authentication and authorization are delegated to external scripts or programs that can integrate with LDAP, Kerberos, custom databases, or other identity providers.
    This mechanism is suitable for enterprise environments requiring centralized identity management or certificate-based security models.
Security Considerations:
  • PLAIN: Always use with TLS/SSL encryption to prevent credential interception. Never use over unencrypted connections in production environments.
  • EXTERNAL: Requires proper certificate management and PKI infrastructure for certificate-based auth, or secure configuration of external authentication backends. Provides stronger authentication but increases setup and maintenance complexity.
Yes PLAIN
rabbitmq.server.user.name Server Username Username for PLAIN authentication. No guest
rabbitmq.server.password Server Password Password for PLAIN authentication. No guest
rabbitmq.connection.oauth2.enabled OAuth2 Enabled Enable if using OAuth 2.0 (e.g., Client Credentials or Password Grant) for authentication instead of a simple username/password. When OAuth 2.0 is enabled, RabbitMQ validates access tokens presented by clients against a configured authorization server. The OAuth 2.0 plugin uses JWT (JSON Web Token) tokens and can verify them either by validating the token's signature using public keys or by introspecting the token with the authorization server. Please refer to the RabbitMQ OAuth 2.0 plugin documentation for detailed configuration instructions and supported Identity providers. No false
rabbitmq.connection.oauth2.token.endpoint Token Endpoint Defines the Identity Provider/Token Service token endpoint URL to generate the access token.

Note

Provide the HTTPS URL for the token endpoint and import the Identity Provider's public certificate into the WSO2 MI client-truststore.jks. See importing SSL certificates to a truststore for instructions on importing the certificate into client-truststore.jks.

No -
rabbitmq.connection.oauth2.grant.type Grant Type Defines the OAuth2 grant type to use for token generation.
Options:
  • client_credentials: Used for machine-to-machine (M2M) authentication where the application authenticates using its own credentials (client ID and client secret) without user involvement. This is the most common grant type for service-to-service communication and background processes. Recommended for most RabbitMQ integration scenarios.
  • password: Also known as Resource Owner Password Credentials (ROPC) grant. The application collects the user's username and password directly and exchanges them for an access token. This grant type should only be used when there is a high degree of trust between the user and the application, as it requires handling user credentials directly. Generally discouraged for security reasons unless legacy systems require it.
No client_credentials
rabbitmq.connection.oauth2.client.id Client ID The client ID for OAuth 2.0 authentication. No -
rabbitmq.connection.oauth2.client.secret Client Secret The client secret for OAuth 2.0 authentication. No -
rabbitmq.connection.oauth2.username User Name Username required when using the password OAuth 2.0 grant type. No -
rabbitmq.connection.oauth2.password Password Password required when using the password OAuth 2.0 grant type. No -
rabbitmq.connection.oauth2.scope Scope Scopes to include in the OAuth 2.0 token request (space-separated if multiple).
The required scopes depend on the RabbitMQ OAuth 2.0 authorization configuration and the intended use case. If the integration only needs to consume and publish messages to RabbitMQ, it can be configured with scopes that grant read and write permissions. However, if the integration also needs to create or manage queues, exchanges, bindings, or other broker resources, additional management-related scopes must be included.

Note

The exact scope values depend on the RabbitMQ OAuth 2.0 configuration. Some deployments may use aliases such as read, write, and management, while others may require RabbitMQ-specific scopes such as rabbitmq.read:/, rabbitmq.write:/, and rabbitmq.configure:/*. Refer to the RabbitMQ OAuth 2.0 documentation for details on scope aliases and scope-to-permission mapping.

No -
Resilience
rabbitmq.connection.idle.timeout Connection Idle Timeout Maximum period (in milliseconds) the connection can remain idle before being closed. No 60000
rabbitmq.connection.establish.retry.count Connection Establish Retry Count Number of times to retry establishing the connection. No 5
rabbitmq.connection.establish.retry.interval Connection Establish Retry Interval Interval (in milliseconds) between retries when establishing the connection. No 1000
rabbitmq.connection.recovery.policy.type Connection Recovery Policy Type Defines the strategy for automatic connection recovery after a disconnection.
Options:
  • FIXED: Attempts to reconnect immediately after a connection failure with a fixed interval between retry attempts. This provides the fastest reconnection but may overwhelm the broker if it's experiencing issues or during network instability.
  • FIXED_WITH_INITIAL_DELAY: Waits for a specified initial delay before attempting the first reconnection, then continues with fixed intervals for subsequent retries. This gives the broker or network time to stabilize before reconnection attempts begin, reducing unnecessary load during transient failures.
  • FIXED_WITH_INITIAL_DELAY_AND_TIMEOUT: Combines an initial delay before the first retry attempt with a maximum timeout limit for the entire recovery process. If the connection cannot be re-established within the timeout period, recovery attempts cease. This prevents indefinite reconnection attempts and allows the application to fail gracefully or implement alternative handling. Recommended for production environments to balance resilience with resource management.
No FIXED_WITH_INITIAL_DELAY_AND_TIMEOUT
rabbitmq.connection.recovery.initial.delay Connection Recovery Initial Delay Initial delay (in milliseconds) before the first recovery attempt starts. No 5000
rabbitmq.connection.recovery.retry.interval Connection Recovery Interval Fixed interval (in milliseconds) between connection recovery retries. No 10000
rabbitmq.connection.recovery.retry.timeout Connection Recovery Timeout Total time (in milliseconds) allowed for the connection recovery process before giving up. No 60000
Queue Properties
rabbitmq.queue.arguments Arguments Additional arguments to customize queue behavior when declaring the queue. Specify as comma-separated key=value pairs (e.g., x-message-ttl=60000,x-max-length=1000).

Common queue arguments:
  • x-message-ttl: Sets the time-to-live (TTL) for messages in milliseconds. Messages older than this value are automatically discarded or dead-lettered. Example: x-message-ttl=60000 (1 minute). Useful for time-sensitive data like session tokens or temporary notifications.
  • x-max-length: Limits the maximum number of messages the queue can hold. When exceeded, the overflow strategy (see queueOverflowStrategy) determines what happens. Example: x-max-length=10000. Prevents unbounded queue growth.
  • x-max-length-bytes: Limits the maximum total size of messages in bytes. Alternative to message count limit. Example: x-max-length-bytes=10485760 (10MB). Useful for controlling memory usage.
  • x-dead-letter-exchange: Specifies the exchange to route dead-lettered messages (expired, rejected, or exceeding delivery limits). Example: x-dead-letter-exchange=dlx. Essential for handling failed or problematic messages.
  • x-dead-letter-routing-key: Optional routing key for dead-lettered messages. If not set, the original routing key is used. Example: x-dead-letter-routing-key=failed.orders.
  • x-expires: Auto-deletes the queue after specified milliseconds of inactivity (no consumers, no messages published). Example: x-expires=1800000 (30 minutes). Useful for temporary or session-based queues.
  • x-single-active-consumer: When set to true, ensures only one consumer receives messages at a time (others are on standby). Example: x-single-active-consumer=true. Useful for ordered processing or leader election patterns.
Format: Use the syntax key1=value1,key2=value2 with no spaces. Numeric values should be in milliseconds for time-based arguments or plain integers/bytes for counts and sizes. Boolean values should be true or false.

Note: Arguments specified here are applied during queue declaration. If the queue already exists with different arguments, the declaration will fail unless the arguments match exactly. Some arguments are queue-type specific (e.g., x-max-priority for CLASSIC queues only). Leave blank if no custom queue arguments are needed.
No -
rabbitmq.classic.version Queue Version For Classic Queues, select the queue implementation version.
Options:
  • V1: The legacy classic queue implementation available in all RabbitMQ versions. Uses the original message storage and indexing mechanism. While mature and stable, it has known performance limitations with large queues, high message rates, and memory efficiency. Consider using V1 only for backward compatibility or if running RabbitMQ versions prior to 3.10.
  • V2: The modern classic queue implementation introduced in RabbitMQ 3.10, also known as CQv2 (Classic Queue version 2). Provides significantly improved performance, memory efficiency, and scalability through optimized message storage and reduced per-message overhead. Offers better handling of large queues (millions of messages) and higher throughput. Recommended for all new deployments and production workloads running RabbitMQ 3.10 or later. Note: Once a queue is created with a specific version, it cannot be changed without recreating the queue.
Important: This setting only applies to CLASSIC queue types and is ignored for QUORUM and STREAM queues.
No -
rabbitmq.classic.dead.letter.strategy Classic Queue Dead Letter Strategy For Classic Queues: defines the strategy for handling messages that fail processing and are negatively acknowledged or rejected.
Options:
  • FIXED_DELAY_RETRYABLE_DISCARD: Implements an automatic retry mechanism with a fixed delay between retry attempts. When a message fails (discard), it is sent to a configured wait/delay queue where it waits for a specified period before being returned to the original queue for reprocessing. This retry cycle continues until either the message is successfully processed or the maximum dead-lettered count is reached, after which the message is routed to the final Dead Letter Queue for terminal handling.

    Required infrastructure:
    • A delay/wait queue with x-message-ttl argument for the retry delay period (e.g., 30000ms for 30-second delays)
    • Dead letter exchange routing configured on the delay queue to return messages to the original queue after TTL expiration
    • rabbitmq.max.dead.lettered.count to prevent infinite retry loops
    • Final DLQ infrastructure (rabbitmq.final.dead.letter.queue.name, rabbitmq.final.dead.letter.exchange.name) to capture poison messages
    Message flow:
    1. Message fails processing in original queue
    2. Dead-lettered to delay queue (with TTL)
    3. After TTL expires, message returns to original queue
    4. Retry processing attempt
    5. Repeat until success or max dead-lettered count reached
    6. If max count exceeded, route to final DLQ
    Use cases:
    • Transient failures: temporary network issues, rate limits, external service unavailability
    • Time-dependent processing: data not yet available but expected soon
    • Resource contention: database locks, API throttling that may clear with delay
    • Circuit breaker patterns: allowing time for downstream services to recover
    Provides automatic recovery without manual intervention but requires more complex infrastructure setup.
  • NON_RETRYABLE_DISCARD: No automatic retry mechanism. Messages that fail processing are immediately routed to the configured Dead Letter Exchange without any retry attempts. Failed messages move directly to the DLQ (via rabbitmq.dead.letter.exchange.name) or, if the max dead-lettered count is configured and exceeded, to the final DLQ. This is the simpler, more straightforward approach with minimal infrastructure requirements.

    Required infrastructure:
    • Dead Letter Exchange (rabbitmq.dead.letter.exchange.name)
    • Dead Letter Queue (rabbitmq.dead.letter.queue.name) bound to the DLX
    • Optional: Final DLQ infrastructure if using rabbitmq.max.dead.lettered.count
    Message flow:
    1. Message fails processing in original queue
    2. Immediately dead-lettered to DLX
    3. Routed to DLQ for manual review or alternative processing
    4. If max dead-lettered count configured and exceeded, routed to final DLQ instead
    Suitable for scenarios where:
    • Failures are permanent: invalid message format, schema violations, business rule violations that won't resolve with time
    • Retry logic is application-managed: consumer application implements its own retry strategy with more sophisticated logic
    • Manual intervention required: failed messages need human review, code fixes, or data corrections before reprocessing
    • Immediate failure notification needed: alerting and monitoring should trigger immediately without delay cycles
    • Simplicity preferred: avoiding the complexity of delay queue infrastructure
    This is the default and recommended option unless you specifically need automatic retry behavior with delays.
Strategy comparison:
Aspect FIXED_DELAY_RETRYABLE_DISCARD NON_RETRYABLE_DISCARD
Infrastructure complexity High (requires delay queues, additional DLX routing) Low (simple DLX → DLQ)
Retry behavior Automatic with fixed delays None (immediate dead-lettering)
Best for Transient failures, external service issues Permanent failures, application-managed retries
Failure detection speed Delayed (after all retry attempts) Immediate

Configuration requirements:
  • Both strategies work with the standard dead letter parameters: rabbitmq.dead.letter.exchange.name, rabbitmq.dead.letter.queue.name, etc.
  • FIXED_DELAY_RETRYABLE_DISCARD additionally requires manual setup of delay queues with TTL and proper DLX routing topology
  • Use rabbitmq.max.dead.lettered.count with both strategies to implement final DLQ routing and prevent infinite cycling
  • Configure retry delays via x-message-ttl on delay queues (not a connector parameter)
Important: This setting only applies to CLASSIC queue types and is ignored for QUORUM and STREAM queues. QUORUM queues use the rabbitmq.quorum.dead.letter.strategy parameter instead, which has different semantics (AT_MOST_ONCE vs AT_LEAST_ONCE delivery guarantees).
No NON_RETRYABLE_DISCARD
rabbitmq.classic.max.priority Max Priority For Classic Queues: defines the maximum priority level the queue should support (valid range: 0-255). When set, this parameter adds the x-max-priority argument to the queue declaration, enabling priority queue functionality.

How it works: Messages published with a priority value (0 to the specified max) are delivered to consumers in priority order, with higher priority messages consumed first. Messages without an explicit priority are treated as priority 0 (lowest).

Performance considerations: Priority queues have additional CPU and memory overhead compared to standard queues. Higher max priority values increase this overhead. For most use cases, a max priority of 10 or less is sufficient and recommended.

Use cases: Suitable for scenarios requiring differentiated message handling, such as urgent alerts, high-priority transactions, or tiered job processing systems.

Important: Priority queues are only supported by CLASSIC queues. This setting is ignored for QUORUM and STREAM queue types. Leave empty or set to 0 to disable priority functionality.
No -
rabbitmq.quorum.initial.member.count Initial Member Count Specifies the initial number of cluster nodes that will host replicas of the queue. This setting applies differently based on queue type:

For Quorum Queues: Defines the initial replication factor (number of replica nodes) for the queue. The default is 3 replicas if not specified, which provides a good balance between availability and resource usage. Quorum queues require a majority (quorum) of replicas to be available for operation. For example, with 3 replicas, the queue tolerates 1 node failure; with 5 replicas, it tolerates 2 node failures. Higher replica counts improve fault tolerance but increase network overhead and resource consumption.

For Stream Queues: Determines the initial number of stream replicas across cluster nodes. Similar to quorum queues, this affects data redundancy and availability. Streams use leader-based replication where one replica is the leader handling writes, while followers replicate data.

Considerations:
  • The cluster must have at least as many nodes as the specified member count
  • Odd numbers (3, 5, 7) are recommended for quorum-based systems to avoid split-brain scenarios
  • Leave blank to use RabbitMQ's default behavior (typically 3 replicas)
Important: This setting only applies to QUORUM and STREAM queue types and is ignored for CLASSIC queues.
No -
rabbitmq.quorum.delivery.limit Delivery Limit For Quorum Queues: defines the maximum number of delivery attempts for a message before it is automatically dead-lettered or discarded. This setting adds the x-delivery-limit argument to the queue declaration.

How it works: When a message is negatively acknowledged (discard) or requeued by a consumer, RabbitMQ increments its delivery counter. Once the delivery count reaches the specified limit, the message is either moved to a configured dead letter exchange (DLX) or dropped if no DLX is configured.

Use cases: Prevents poison messages (messages that repeatedly fail processing) from blocking the queue indefinitely. Essential for building resilient systems where problematic messages can be isolated for manual inspection or alternative handling without affecting other messages.

Best practices:
  • Always configure a dead letter exchange when using delivery limits to capture failed messages for analysis
  • Typical values range from 3-10 depending on your tolerance for retries
  • Consider implementing exponential backoff in consumers before relying solely on delivery limits
Important: This setting only applies to QUORUM queue types and is ignored for CLASSIC and STREAM queues. Leave blank to disable delivery limit enforcement (messages can be redelivered indefinitely).
No -
rabbitmq.quorum.dead.letter.strategy Quorum Queue Dead Letter Strategy For Quorum Queues: defines how messages are handled when being dead-lettered, controlling the delivery guarantee semantics. This setting adds the x-dead-letter-strategy argument to the queue declaration. Options:
  • AT_MOST_ONCE: The default and safer strategy. Messages are removed from the original queue before being published to the dead letter exchange (DLX). This guarantees that a message will not be duplicated if the dead-lettering process fails - it will either be in the original queue or successfully dead-lettered, but never in both. However, in case of broker failure during dead-lettering, the message may be lost. Recommended for most use cases where preventing duplicate processing is more critical than preventing message loss.
  • AT_LEAST_ONCE: Messages are published to the dead letter exchange first, then removed from the original queue only after successful publication. This ensures no message is lost during the dead-lettering process, but in case of failures, the same message might be dead-lettered multiple times, resulting in duplicates in the DLX. Use this when message loss is unacceptable and your downstream systems can handle duplicate messages (idempotent processing).
Trade-offs:
  • AT_MOST_ONCE: Prevents duplicates, risks message loss on failure
  • AT_LEAST_ONCE: Prevents message loss, risks duplicates on failure
Important: This setting only applies to QUORUM queue types and requires a dead letter exchange to be configured. It is ignored for CLASSIC and STREAM queues.
No -
rabbitmq.stream.initial.member.count Initial Member Count For STREAM queues: specifies the initial number of cluster nodes that will host replicas of the stream. This setting adds the x-initial-cluster-size argument to the stream queue declaration.

How it works: Stream queues use leader-based replication where one replica serves as the leader handling all write operations, while follower replicas asynchronously replicate data for redundancy and availability. The initial member count determines how many replicas are created when the stream is first declared.

Default behavior: If not specified, RabbitMQ uses a default value of 3 replicas, which provides a good balance between data safety and resource usage. With 3 replicas, the stream can tolerate the loss of up to 2 nodes while maintaining data availability (though writes require the leader to be available).

Fault tolerance:
  • 1 replica: No redundancy - node failure results in data loss until recovery
  • 3 replicas: Tolerates 2 node failures for read operations; leader failure requires failover
  • 5 replicas: Higher redundancy but increased network and storage overhead
Considerations:
  • The cluster must have at least as many available nodes as the specified member count
  • Higher replica counts improve data durability but increase disk usage (each replica stores a complete copy) and network traffic (replication overhead)
  • Unlike quorum queues, streams don't require a quorum for operation - only the leader needs to be available for writes
  • Replicas can be added or removed after stream creation using RabbitMQ management commands
Important: This setting only applies to STREAM queue types and is ignored for CLASSIC and QUORUM queues. Leave blank to use the RabbitMQ default (3 replicas).
No -
rabbitmq.stream.max.age Max Age (Seconds) For STREAM queues: defines the maximum time-based retention period for messages in the stream. This setting adds the x-max-age argument to the queue declaration.

How it works: Messages older than the specified age are automatically deleted from the stream to manage disk space. Age is calculated from the message timestamp. The retention policy is evaluated periodically, not in real-time, so messages may persist slightly beyond the specified age.

Format: Specify the duration using time units:
  • Y - Years (e.g., 1Y)
  • M - Months (e.g., 3M)
  • D - Days (e.g., 7D)
  • h - Hours (e.g., 24h)
  • m - Minutes (e.g., 30m)
  • s - Seconds (e.g., 3600s)
Use cases: Essential for managing storage costs and compliance requirements in event streaming scenarios. For example, audit logs might retain data for 90 days, while real-time analytics streams might only need 24 hours.

Considerations:
  • Can be combined with maxLengthBytes - whichever limit is reached first triggers deletion
  • Deleted messages cannot be recovered
  • Leave blank for unlimited retention (not recommended for production - may exhaust disk space)
Important: This setting only applies to STREAM queue types and is ignored for CLASSIC and QUORUM queues.
No -
rabbitmq.stream.max.segment.size Max Segment Size (Bytes) For STREAM queues: defines the maximum size in bytes for individual segment files in the stream's underlying storage. This setting adds the x-stream-max-segment-size-bytes argument to the queue declaration.

How it works: RabbitMQ streams store messages in append-only segment files on disk. When a segment reaches the specified size, it is closed and a new segment is created. Smaller segments are rotated more frequently, while larger segments reduce the number of files but increase individual file sizes.

Performance implications:
  • Smaller segments (e.g., 100MB-250MB): More frequent rotation, faster deletion of old data when retention policies apply, better for scenarios with frequent retention policy enforcement, but higher file system overhead
  • Larger segments (e.g., 500MB-1GB): Fewer files, reduced I/O overhead, better sequential write performance, but slower retention cleanup and potentially longer recovery times
Default behavior: If not specified, RabbitMQ uses a default value of 500MB (524,288,000 bytes), which balances performance and manageability for most workloads.

Best practices:
  • Consider your retention period: shorter retention periods benefit from smaller segments for faster cleanup
  • Match to your message rate: high-throughput streams may benefit from larger segments
  • Ensure adequate disk I/O capacity for your chosen segment size
  • Typical range: 100MB to 1GB depending on workload characteristics
Important: This setting only applies to STREAM queue types and is ignored for CLASSIC and QUORUM queues. Leave blank to use the RabbitMQ default (500MB).
No -
rabbitmq.queue.exclusive Exclusive If enabled, the queue is deleted when the declaring connection closes. Only one consumer can use it. No false
rabbitmq.queue.auto.delete Auto Delete If enabled, the queue is deleted when the last consumer disconnects. No false
Exchange Properties
rabbitmq.header.exchange.binding.arguments Header Exchange Binding Arguments For HEADERS exchanges: defines the header matching criteria used to route messages from the exchange to the bound queue. Specify as comma-separated key=value pairs (e.g., x-match=all,format=pdf,type=report).

Required argument:
  • x-match: Controls the matching logic for header-based routing. Must be specified for HEADERS exchange bindings.
    • x-match=any: Routes the message if any of the binding headers match the message headers. Acts as a logical OR operation. Example: binding with x-match=any,priority=high,urgent=true will match messages with either priority=high OR urgent=true (or both).
    • x-match=all: Routes the message only if all binding headers match the message headers. Acts as a logical AND operation. Example: binding with x-match=all,format=pdf,type=report requires both format=pdf AND type=report in the message headers for routing to succeed.
Additional headers: Any other key=value pairs specified (beyond x-match) define the actual header criteria for matching. Message headers must contain matching key-value pairs according to the x-match logic.

Format: Use the syntax x-match=any|all,header1=value1,header2=value2. Header values are case-sensitive and must match exactly.

Examples:
  • x-match=all,type=order,priority=high - Matches only messages with both headers
  • x-match=any,region=us,region=eu - Matches messages from either US or EU region
  • x-match=all,format=json - Matches only JSON format messages
Important: This setting only applies when using HEADERS exchange type and is ignored for DIRECT, FANOUT, and TOPIC exchanges. Messages are evaluated based on their header properties, not their routing key.
No -
rabbitmq.exchange.arguments Arguments Additional arguments to customize exchange behavior when declaring the exchange. Specify as comma-separated key=value pairs (e.g., alternate-exchange=my-ae,internal=true).

Common exchange arguments:
  • alternate-exchange: Specifies an alternate exchange to route messages that cannot be routed by the primary exchange (no matching bindings). Useful for capturing unroutable messages instead of returning them to the publisher or silently dropping them. Example: alternate-exchange=unrouted-messages
  • internal: When set to true, marks the exchange as internal, preventing direct publishing from clients. Internal exchanges can only receive messages from other exchanges via exchange-to-exchange bindings. Useful for building complex routing topologies. Example: internal=true
Format: Use the syntax key1=value1,key2=value2 with no spaces around the equals sign or commas. Boolean values should be specified as true or false.

Use cases:
  • Alternate exchanges: Error handling, audit trails for unrouted messages, fallback routing
  • Internal exchanges: Multi-stage routing pipelines, routing abstraction layers, exchange federation
Note: Arguments specified here are applied during exchange declaration. If the exchange already exists with different arguments, the declaration will fail unless the arguments match exactly. Leave blank if no custom exchange arguments are needed.
No -
rabbitmq.exchange.auto.delete Auto Delete If enabled, the exchange is deleted when the last queue is unbound. No false
Stream Properties
rabbitmq.stream.filters Stream Filters For STREAM queues: specifies filter values to selectively consume messages from the stream based on the filter-value message property. Provide as comma-separated values (e.g., order,payment,shipment).

How it works: When publishing messages to a stream, producers can attach a filter-value property to each message (e.g., filter-value=order). Consumers specify which filter values they're interested in, and the stream server only delivers matching messages, significantly reducing network bandwidth and consumer processing overhead. Messages without a filter value are excluded unless rabbitmq.stream.filter.match.unfiltered is enabled.

Use cases: Multi-tenant systems (filter by tenant ID), event type filtering (orders vs payments vs notifications), regional data segregation (US vs EU messages), or any scenario where different consumers need different subsets of the same stream.

Benefits: Server-side filtering reduces network traffic and consumer CPU usage compared to client-side filtering. Particularly valuable for high-volume streams where consumers only need a small percentage of messages.

Important: This setting only applies to STREAM queue types. Leave blank to consume all messages without filtering.
No -
rabbitmq.stream.filter.match.unfiltered Stream Filter Match Unfiltered Controls whether messages without a filter-value property are included in consumption when stream filters are active.

Behavior:
  • false (default): Only messages with matching filter values are consumed. Messages without any filter value are skipped entirely. Use this for strict filtering where all relevant messages are guaranteed to have filter values.
  • true: Consumes both messages matching the specified filters AND messages without any filter value. Useful during migration periods when some producers haven't yet adopted filter values, or for backward compatibility with legacy messages.
Example: If filters are set to order,payment:
  • With false: Only messages with filter-value=order or filter-value=payment are consumed
  • With true: Messages with filter-value=order, filter-value=payment, OR no filter value are consumed
Important: This setting is only relevant when rabbitmq.stream.filters is specified and applies only to STREAM queues.
No false
rabbitmq.stream.offset.starting.value Offset Value Specifies the exact stream offset (message position) from which to start consuming messages. When set, this value takes precedence over rabbitmq.stream.offset.starting.strategy.

How it works: Stream offsets are sequential numeric positions representing each message in the stream (similar to Kafka offsets). By providing a specific offset value, you can resume consumption from an exact point in the stream's history, enabling precise replay or recovery scenarios.

Use cases:
  • Replaying messages from a known checkpoint after processing failures
  • Starting consumption from a specific timestamp-derived offset
  • Debugging or auditing specific message ranges
  • Implementing custom offset management strategies
Considerations:
  • The specified offset must exist in the stream (not already deleted by retention policies)
  • Invalid offsets may cause consumer errors or default to earliest/latest available offset
  • This overrides the offset strategy, so the strategy setting is ignored when a value is provided
Important: This setting only applies to STREAM queue types. Leave blank to use the offset strategy instead.
No -
rabbitmq.stream.offset.starting.strategy Offset Strategy Defines the starting position in the stream when beginning message consumption. This setting is ignored if rabbitmq.stream.offset.starting.value is specified. Options:
  • FIRST: Starts consumption from the earliest available message in the stream (beginning of retained history). All messages currently in the stream will be delivered, making this suitable for complete replay scenarios, initial data synchronization, or catch-up processing. Note: The actual starting point depends on the stream's retention policy - messages deleted due to age or size limits are not available.
  • LAST: Starts consumption from the most recent message in the stream at the time the consumer connects. Historical messages are skipped, and only newly arriving messages (published after consumer connection) are delivered. Useful for real-time processing where historical data is irrelevant, such as live monitoring dashboards or current event processing.
  • NEXT: Waits for new messages to arrive and only consumes messages published after the consumer attaches. Similar to LAST but with clearer semantics - guaranteed not to consume any existing messages, only future ones. Ideal for new consumers joining a stream where no historical context is needed, such as new microservice instances or fresh monitoring agents. This is the default and safest option for new consumers.
Important: This setting only applies to STREAM queue types and is used only when rabbitmq.stream.offset.starting.value is not specified.
No NEXT
rabbitmq.stream.offset.tracker.flush.interval Offset Tracker Flush Interval (Seconds) Defines how frequently (in seconds) the consumer's current processing offset is persisted to the WSO2 MI server.

How it works: As the consumer processes messages, it tracks the last successfully processed offset in memory. This interval determines how often that in-memory offset is flushed (committed) to the server, allowing the consumer to resume from the last committed position after restarts or failures.

Trade-offs:
  • Lower values (e.g., 1-5 seconds): More frequent commits reduce the number of duplicate messages reprocessed after consumer restarts/crashes, but increase server-side I/O overhead.
  • Higher values (e.g., 30-60 seconds): Reduced overhead and better performance, but more messages may be redelivered (duplicates) after failures since the last flush occurred further in the past.
Default: 10 seconds provides a reasonable balance for most workloads. Adjust based on your message processing rate and tolerance for duplicate processing.

Important: This setting only applies to STREAM queue types. Offset tracking enables automatic resume functionality - without it, consumers would restart from their configured starting strategy on every reconnection.
No 10
rabbitmq.stream.offset.tracker.shutdown.timeout Offset Tracker Shutdown Timeout (Seconds) Specifies the maximum time (in seconds) to wait for the offset tracker to flush the current offset to the server during graceful WSO2 MI Server shutdown.

How it works: When the WSO2 MI Server shuts down gracefully (not a crash), it attempts to commit its latest processed offset one final time before disconnecting. This timeout controls how long the shutdown process will wait for that final flush operation to complete.

Behavior:
  • If the flush completes within the timeout, the consumer resumes from the exact last processed message on restart (no duplicates or gaps)
  • If the timeout expires before flushing completes, shutdown proceeds anyway, and the consumer may reprocess some messages on restart (back to the last successfully flushed offset)
Considerations:
  • Too short (< 2 seconds): May not allow enough time for network latency or server processing, resulting in lost offset commits
  • Too long (> 30 seconds): Delays MI Server shutdown unnecessarily, especially problematic in containerized environments with fast restart cycles
Default: 5 seconds is typically sufficient for most network conditions while keeping shutdown responsive.

Important: This setting only applies to STREAM queue types and only affects graceful shutdown scenarios. Crashes or forced terminations cannot benefit from this timeout.
No 5
SSL Configurations
rabbitmq.connection.ssl.enabled Enabled Enable SSL/TLS for the RabbitMQ connection. No false
rabbitmq.connection.ssl.trust.everything Trust Everything If enabled, all server certificates are accepted. Not recommended for production. No false
rabbitmq.connection.ssl.keystore.location Keystore Location File path to the Keystore containing the client's private key and certificate. No -
rabbitmq.connection.ssl.keystore.type Keystore Type The type of the Keystore (e.g., JKS). No JKS
rabbitmq.connection.ssl.keystore.password Keystore Password The password to access the Keystore. No -
rabbitmq.connection.ssl.truststore.location Truststore Location File path to the Truststore containing trusted server certificates. No -
rabbitmq.connection.ssl.truststore.type Truststore Type The type of the Truststore (e.g., JKS). No JKS
rabbitmq.connection.ssl.truststore.password Truststore Password The password to access the Truststore. No -
rabbitmq.connection.ssl.version SSL Version The preferred SSL/TLS protocol version (e.g., 'TLSv1.2', 'TLSv1.3'). No -
rabbitmq.connection.ssl.hostname.verification.enabled Enabled SSL Hostname Verification If enabled, verifies the hostname in the server's certificate against the connected host name. No false
Dead-Letter Configurations
rabbitmq.dead.letter.queue.name Dead Letter Queue Name The name of the Dead Letter Queue (DLQ) where failed or rejected messages are stored for inspection, reprocessing, or archival.

Purpose: The DLQ serves as a holding area for messages that cannot be successfully processed, including:
  • Messages rejected by consumers (nack/reject with requeue=false)
  • Messages exceeding the delivery limit in Quorum queues
  • Expired messages (TTL exceeded)
  • Messages from full queues with overflow strategies that use dead-lettering
Best practices:
  • Use descriptive naming conventions (e.g., orders.dlq, payments.dead-letter)
  • Configure monitoring and alerts on DLQ depth to detect systematic processing failures
  • Implement processes for reviewing and reprocessing or discarding DLQ messages
  • Consider using a durable queue type (QUORUM recommended) to prevent DLQ message loss
Important: This queue must be bound to the Dead Letter Exchange specified in rabbitmq.dead.letter.exchange.name using the routing key from rabbitmq.dead.letter.routing.key (for DIRECT exchanges).
No -
rabbitmq.dead.letter.queue.type Dead Letter Queue Type Defines the queue type for the Dead Letter Queue. Options:
  • CLASSIC: The traditional queue type with lower overhead and simpler configuration. Suitable for development environments or non-critical DLQs where message loss is acceptable. Messages are stored on a single node with optional mirroring (deprecated in RabbitMQ 3.12+).
  • QUORUM: Replicated queue type providing high availability and data safety through Raft consensus. Recommended for production environments where failed messages must be preserved reliably. Ensures DLQ messages survive node failures through automatic replication across cluster nodes. Slightly higher resource usage but significantly better durability guarantees.
Recommendation: Use QUORUM for production DLQs to ensure failed messages aren't lost during infrastructure issues. This is especially important since DLQ messages often represent valuable data requiring investigation or manual intervention.

Important: This setting is only used if rabbitmq.dead.letter.queue.auto.declare is enabled. If the queue already exists, its type cannot be changed without deleting and recreating it.
No CLASSIC
rabbitmq.dead.letter.queue.auto.declare Dead Letter Queue Auto Declare Controls whether the system automatically creates the Dead Letter Queue if it doesn't already exist.

Behavior:
  • true: The Dead Letter Queue is automatically declared (created) when the inbound endpoint starts, using the type specified in rabbitmq.dead.letter.queue.type. Convenient for development, testing, or simple deployments where infrastructure management is automated.
  • false (default): The Dead Letter Queue must be pre-created manually or through infrastructure-as-code tools. Recommended for production environments where queue topology is managed centrally, versioned, and deployed through controlled processes (Terraform, Ansible, RabbitMQ management policies).
Considerations:
  • Auto-declaration may cause startup failures if permissions are insufficient or if a queue with the same name but different properties already exists
  • Manual declaration allows for more precise control over queue arguments, durability settings, and cluster placement
  • In production, prefer pre-creating queues to avoid unexpected topology changes during application deployments
No false
rabbitmq.dead.letter.exchange.name Dead Letter Exchange Name The name of the Dead Letter Exchange (DLX) responsible for routing dead-lettered messages from the primary queue to the Dead Letter Queue.

How it works: When messages are dead-lettered (rejected, expired, or exceeding delivery limits), they are republished to this exchange instead of being discarded. The exchange then routes them to bound queue(s) based on the exchange type and routing rules, typically the configured DLQ.

Architecture patterns:
  • Dedicated DLX per queue: Each primary queue has its own DLX (e.g., orders.dlx, payments.dlx) for isolated failure handling
  • Shared DLX: Multiple queues route to a common DLX (e.g., app.dlx) with routing keys distinguishing the source queue
Best practices:
  • Use clear naming conventions indicating purpose (e.g., service-name.dlx)
  • Ensure the DLX exists before configuring it on queues (or enable auto-declare)
  • The primary queue must have this DLX configured via the x-dead-letter-exchange queue argument
No -
rabbitmq.dead.letter.exchange.type Dead Letter Exchange Type Defines the exchange type for the Dead Letter Exchange, determining how dead-lettered messages are routed. Options:
  • DIRECT: Routes messages based on an exact routing key match. Dead-lettered messages are published with either their original routing key or the routing key specified in rabbitmq.dead.letter.routing.key (if configured). Use DIRECT when you need to route failed messages from different source queues to different DLQs, or when you want to preserve routing semantics. Requires binding the DLQ with the appropriate routing key.
  • FANOUT: Broadcasts all dead-lettered messages to all queues bound to the DLX, ignoring routing keys. Simpler configuration since no routing key matching is needed. Use FANOUT when all dead-lettered messages should go to the same destination(s) regardless of source or when multiple DLQ consumers need copies of every failed message (e.g., for monitoring and archival simultaneously).
Recommendation: DIRECT is more common as it provides flexibility for routing to specific DLQs based on message origin or failure type. FANOUT is simpler but less flexible.

Important: This setting is only used if rabbitmq.dead.letter.exchange.auto.declare is enabled. If using DIRECT, ensure rabbitmq.dead.letter.routing.key is configured.
No DIRECT
rabbitmq.dead.letter.exchange.auto.declare Dead Letter Exchange Auto Declare Controls whether the system automatically creates the Dead Letter Exchange if it doesn't already exist.

Behavior:
  • true: The Dead Letter Exchange is automatically declared (created) when the inbound endpoint starts, using the type specified in rabbitmq.dead.letter.exchange.type. Convenient for development, testing, or automated deployment scenarios.
  • false (default): The Dead Letter Exchange must be pre-created manually or through infrastructure management tools. Recommended for production environments where exchange topology is managed centrally and changes are version-controlled.
Considerations:
  • Auto-declaration requires appropriate permissions and may fail if an exchange with the same name but different type already exists
  • Manual declaration allows better control over exchange durability, internal flags, and other advanced properties
  • In multi-service architectures, centralized exchange management prevents conflicts and ensures consistency
No false
rabbitmq.dead.letter.routing.key Dead Letter Routing Key Specifies the routing key used when publishing dead-lettered messages to a DIRECT Dead Letter Exchange. This overrides the message's original routing key.

How it works: When a message is dead-lettered and the DLX is of type DIRECT, this routing key is used to route the message to bound queue(s). The DLQ must be bound to the DLX with a matching routing key for messages to be delivered.

Common patterns:
  • Static routing key: Use a fixed value like failed or dlq for all dead-lettered messages from this queue
  • Source-based routing: Use descriptive keys like orders.failed, payments.rejected to identify the source queue
  • Preserve original: Leave blank to use the message's original routing key (useful for maintaining routing context)
Example configuration:
  • DLX: app.dlx (DIRECT)
  • Dead Letter Routing Key: orders.failed
  • DLQ Binding: Queue orders.dlq bound to app.dlx with routing key orders.failed
Important: This setting is only relevant when rabbitmq.dead.letter.exchange.type is DIRECT. It is ignored for FANOUT exchanges. Leave blank to preserve the original message routing key.
No -
rabbitmq.dead.letter.queue.message.ttl Dead Letter Queue Message TTL Time-to-live (TTL) in milliseconds for messages in the Dead Letter Queue before being retried or discarded. No -
rabbitmq.max.dead.lettered.count Max Dead Lettered Count Defines the maximum number of times a message can cycle through the dead-lettering process before being routed to the final Dead Letter Queue, preventing infinite retry loops.

How it works: RabbitMQ tracks the number of times a message has been dead-lettered using the x-death message header. Each time a message is dead-lettered, this counter increments. When the count reaches the specified limit, the message is routed to the final DLQ (configured via rabbitmq.final.dead.letter.queue.name) instead of the regular DLQ, effectively removing it from the retry cycle.

Use cases:
  • Retry with delay: Combined with TTL-based delay queues, implements automatic retry with backoff (message goes to DLQ with TTL, then back to original queue, repeat until max count)
  • Poison message protection: Prevents messages that consistently fail from cycling indefinitely and consuming resources
  • Tiered failure handling: Allows different handling for transient failures (regular DLQ) vs persistent failures (final DLQ)
Typical values:
  • 3-5: Suitable for retry scenarios with moderate failure tolerance
  • 10+: For scenarios where extensive retry attempts are acceptable before final abandonment
Important: Requires configuring the final DLQ infrastructure (rabbitmq.final.dead.letter.queue.name, rabbitmq.final.dead.letter.exchange.name). Leave blank to disable the final DLQ mechanism (messages can be dead-lettered indefinitely).
No -
rabbitmq.final.dead.letter.queue.name Final Dead Letter Queue Name The name of the final Dead Letter Queue where messages are sent after exceeding the maximum dead-lettered count specified in rabbitmq.max.dead.lettered.count.

Purpose: The final DLQ serves as the terminal destination for poison messages - messages that have repeatedly failed processing despite multiple retry attempts. These messages are typically:
  • Structurally invalid or corrupted data that cannot be parsed
  • Business logic violations that won't resolve with retries
  • Messages requiring code changes or manual intervention to process
Best practices:
  • Use distinct naming (e.g., orders.final-dlq, payments.poison-messages) to clearly differentiate from the regular DLQ
  • Implement separate monitoring and alerting for the final DLQ - messages here represent systematic issues
  • Configure longer retention or persistent storage since these messages often require manual analysis
  • Consider periodic review processes to identify patterns in final DLQ messages and address root causes
Important: Only used when rabbitmq.max.dead.lettered.count is configured. Must be bound to the final DLX specified in rabbitmq.final.dead.letter.exchange.name.
No -
rabbitmq.final.dead.letter.queue.type Final Dead Letter Queue Type Defines the queue type for the final Dead Letter Queue. Options:
  • CLASSIC: Traditional queue type with simpler configuration and lower overhead. May be acceptable for final DLQs with low message volumes or where loss is tolerable (messages can be re-generated from source systems).
  • QUORUM: Replicated queue type with high availability and durability. Strongly recommended for final DLQs since these messages represent critical failures that must be preserved for investigation. Ensures poison messages survive node failures and aren't lost during cluster maintenance.
Recommendation: Use QUORUM for production final DLQs. Messages in the final DLQ often contain valuable diagnostic information about systematic processing failures and should be reliably preserved.

Important: This setting is only used if rabbitmq.final.dead.letter.queue.auto.declare is enabled. The queue type cannot be changed after creation without deleting and recreating the queue.
No CLASSIC
rabbitmq.final.dead.letter.queue.auto.declare Final Dead Letter Queue Auto Declare Controls whether the system automatically creates the final Dead Letter Queue if it doesn't already exist.

Behavior:
  • true: The final Dead Letter Queue is automatically declared when the inbound endpoint starts, using the type from rabbitmq.final.dead.letter.queue.type. Convenient for development or automated deployments.
  • false (default): The final DLQ must be pre-created manually or through infrastructure automation. Recommended for production where queue topology is centrally managed and version-controlled.
Considerations: Same as rabbitmq.dead.letter.queue.auto.declare - production environments typically benefit from explicit infrastructure management rather than runtime auto-creation.
No false
rabbitmq.final.dead.letter.exchange.name Final Dead Letter Exchange Name The name of the final Dead Letter Exchange used to route messages that have exceeded the maximum dead-lettered count to the final DLQ.

How it works: When a message's dead-letter count reaches rabbitmq.max.dead.lettered.count, it is published to this exchange instead of the regular DLX. This exchange then routes the message to the final DLQ, removing it from the retry cycle.

Architecture patterns:
  • Separate final DLX: Use a distinct exchange (e.g., app.final-dlx) to clearly separate retry logic from terminal failure handling
  • Shared with regular DLX: Reuse the same exchange with different routing keys to distinguish regular vs final dead-lettering (less common but simpler topology)
Important: Only used when rabbitmq.max.dead.lettered.count is configured. The final DLQ must be bound to this exchange with the appropriate routing key (if DIRECT) or simply bound (if FANOUT).
No -
rabbitmq.final.dead.letter.exchange.type Final Dead Letter Exchange Type Defines the exchange type for the final Dead Letter Exchange. Options:
  • DIRECT: Routes messages based on routing key matching. Provides flexibility for routing poison messages to different final destinations based on source queue or failure type. Requires configuring rabbitmq.final.dead.letter.routing.key and binding the final DLQ with matching routing key.
  • FANOUT: Broadcasts all poison messages to all bound queues. Simpler configuration with no routing key management needed. Use when all poison messages should go to the same final DLQ regardless of source.
Recommendation: DIRECT is more common for flexibility, but FANOUT is simpler when routing complexity isn't needed.

Important: This setting is only used if rabbitmq.final.dead.letter.exchange.auto.declare is enabled.
No DIRECT
rabbitmq.final.dead.letter.exchange.auto.declare Final Dead Letter Exchange Auto Declare Controls whether the system automatically creates the final Dead Letter Exchange if it doesn't already exist.

Behavior:
  • true: The final Dead Letter Exchange is automatically declared when the inbound endpoint starts, using the type from rabbitmq.final.dead.letter.exchange.type.
  • false (default): The final DLX must be pre-created manually or through infrastructure management tools.
Considerations: Same as rabbitmq.dead.letter.exchange.auto.declare - production environments typically benefit from centralized exchange management.
No false
rabbitmq.final.dead.letter.routing.key Final Dead Letter Routing Key Specifies the routing key used when publishing poison messages (exceeding max dead-lettered count) to a DIRECT final Dead Letter Exchange.

How it works: When a message reaches the maximum dead-letter count and the final DLX is DIRECT, this routing key determines how the message is routed to the final DLQ. The final DLQ must be bound to the final DLX with a matching routing key.

Common patterns:
  • Fixed poison key: Use values like poison, failed-final, or abandoned
  • Source-based: Include source identification like orders.poison, payments.final-failure
  • Preserve original: Leave blank to use the message's original routing key
Important: Only relevant when rabbitmq.final.dead.letter.exchange.type is DIRECT. Ignored for FANOUT exchanges. Leave blank to preserve the original message routing key.
No -
rabbitmq.dead.letter.publisher.retry.interval Dead Letter Publisher Retry Interval (ms) Defines the initial interval (in milliseconds) between retry attempts when publishing a message to the Dead Letter Queue fails.

How it works: If publishing to the DLQ fails due to network issues, broker unavailability, or resource constraints, the system waits this duration before attempting to republish. Combined with the exponential factor, subsequent retries wait progressively longer (e.g., 10s, 20s, 40s with factor 2.0).

Use cases for retry: DLQ publishing can fail due to:
  • Temporary network partitions or connectivity issues
  • Broker resource limits (memory, disk space)
  • Queue length or size limits on the DLQ itself
  • Brief broker unavailability during restarts or failovers
Typical values:
  • 5000-10000ms (5-10 seconds): Balances quick recovery with avoiding excessive retry storms
  • Shorter (1000-3000ms): For scenarios where DLQ availability is critical and failures are expected to be very brief
  • Longer (30000ms+): When DLQ publishing is low priority and can tolerate extended delays
Default: 10000ms (10 seconds) provides reasonable balance for most scenarios.
No 10000
rabbitmq.dead.letter.publisher.retry.count Dead Letter Publisher Retry Count Specifies the maximum number of retry attempts when publishing to the Dead Letter Queue fails.

How it works: After the initial publish attempt fails, the system retries up to this many times before giving up. Each retry waits progressively longer based on the retry interval and exponential factor.

Failure handling: After exhausting all retries:
  • The failed message is typically logged with full details for manual recovery
  • The original message may be lost if no other fallback mechanism exists
  • Monitoring should alert on DLQ publish failures to enable manual intervention
Typical values:
  • 3-5 retries: Balances recovery attempts with preventing indefinite blocking. Default is 3.
  • 0-1 retries: For fail-fast scenarios where DLQ unavailability should immediately escalate to alerts
  • 10+ retries: For critical systems where every failed message must be captured, accepting longer delays
Consideration: Higher retry counts with exponential backoff can result in very long total retry periods. For example, 3 retries with 10s initial interval and 2.0 factor = 10s + 20s + 40s = 70s total retry time.
No 3
rabbitmq.dead.letter.publisher.retry.exponential.factor Dead Letter Publisher Retry Exponential Factor Defines the exponential backoff multiplier applied to the retry interval for subsequent retry attempts when DLQ publishing fails.

How it works: Each retry attempt waits for interval × (factor ^ attempt_number). For example:
  • Initial interval: 10000ms, Factor: 2.0
  • 1st retry: 10000ms (10s)
  • 2nd retry: 20000ms (20s) - interval × 2.0
  • 3rd retry: 40000ms (40s) - interval × 2.0²
Purpose: Exponential backoff prevents overwhelming a struggling broker with rapid retry attempts while still allowing quick recovery for transient failures. Longer delays between retries give the broker time to recover from resource constraints or complete maintenance operations.

Typical values:
  • 2.0 (default): Doubles the wait time with each retry - aggressive but reasonable
  • 1.5: More gradual backoff for scenarios where quick retry is preferred
  • 3.0: Aggressive backoff when broker recovery is expected to take longer
  • 1.0: No exponential backoff - fixed interval between all retries
Important: Setting this to 1.0 disables exponential backoff, resulting in fixed-interval retries. Values less than 1.0 would decrease intervals (not recommended).
No 2.0
rabbitmq.dead.letter.publisher.ack.wait.time Dead Letter Publisher Broker ACKNOWLEDGE Waiting Time (ms) Specifies the maximum time (in milliseconds) to wait for the RabbitMQ broker to acknowledge successful receipt of a dead-lettered message when using publisher confirms.

How it works: When publisher confirms are enabled (recommended for reliability), the broker sends an acknowledgment after successfully persisting the message. This timeout controls how long the publisher waits for that acknowledgment before considering the publish operation failed.

Timeout scenarios:
  • Broker overload: High message volumes or resource constraints may delay acknowledgments
  • Network latency: Slow or unstable network connections between client and broker
  • Disk I/O delays: Slow disk writes for durable queues or mirrored/quorum queues
  • Cluster synchronization: Quorum queues require majority consensus before acknowledging
Typical values:
  • 10000-30000ms (10-30 seconds): Default is 30000ms. Sufficient for most scenarios including quorum queues
  • Shorter (5000ms): For low-latency environments with fast disks and minimal network latency
  • Longer (60000ms+): For distributed clusters or environments with known slow disk I/O
Failure handling: If the timeout expires without receiving an acknowledgment, the publish is considered failed and retry logic (if configured) is triggered.

Important: This timeout should be longer than typical publish latencies to avoid false failures. Monitor actual acknowledgment times to tune appropriately.
No 30000
rabbitmq.dead.letter.publisher.shutdown.timeout Dead Letter Publisher Shutdown Timeout (ms) Defines the maximum time (in milliseconds) to wait for the dead letter publisher to complete pending operations and shut down gracefully during application shutdown.

How it works: When the application begins shutdown, the dead letter publisher attempts to:
  • Complete any in-flight publish operations and await acknowledgments
  • Flush any buffered messages to the broker
  • Retry any failed publishes within the remaining timeout window
  • Close connections and release resources cleanly
If these operations don't complete within the timeout, the publisher is forcefully terminated, potentially losing messages that were in the process of being published.

Typical values:
  • 60000-180000ms (1-3 minutes): Default is 180000ms (3 minutes). Allows time for retries and acknowledgments
  • Shorter (30000ms): For environments requiring fast shutdown cycles, accepting higher risk of message loss
  • Longer (300000ms+): For critical systems where DLQ message loss is unacceptable and longer shutdown is tolerable
Considerations:
  • Should be longer than (retry.interval × exponential.factor ^ retry.count) + ack.wait.time to allow full retry cycles
  • In containerized environments (Kubernetes, Docker), ensure this timeout is shorter than the container termination grace period
  • Longer timeouts delay application shutdown but improve message reliability
Important: Failed messages not successfully published within this timeout may be lost. Consider implementing persistent local buffering if message loss during shutdown is unacceptable.
No 180000
Throttling Configurations
rabbitmq.throttle.enabled Throttling Enabled Controls whether message consumption rate limiting is active. When enabled, the consumer will throttle message processing according to the configured throttling mode, time unit, and count limits.

Purpose: Throttling prevents overwhelming downstream systems, controls resource consumption, enforces API rate limits, or ensures compliance with service-level agreements (SLAs) that specify maximum processing rates.

Use cases:
  • External API rate limits: Processing messages that call third-party APIs with strict rate limits (e.g., 1000 calls/hour)
  • Database protection: Limiting write operations to prevent overloading databases during peak message volumes
  • Cost control: Capping processing rates to control consumption-based costs (API calls, cloud resources)
  • Quality of service: Ensuring fair resource allocation across multiple consumers or message types
  • Gradual rollout: Slowly ramping up processing during new feature deployments or system migrations
Behavior:
  • true: Message consumption is limited according to rabbitmq.throttle.mode, rabbitmq.throttle.timeUnit, and rabbitmq.throttle.count
  • false (default): No throttling applied - messages are consumed as fast as the consumer can process them
Important: Throttling affects consumer throughput and may cause queue backlog if message arrival rate exceeds the throttling limit. Monitor queue depth and adjust limits appropriately.
No false
rabbitmq.throttle.mode Throttling Mode Defines the strategy for applying rate limiting to message consumption. Options:
  • FIXED_INTERVAL: Enforces a fixed delay between consecutive message processing operations. The delay is calculated to achieve the target rate: delay = (timeUnit in ms) / count. For example, to process 60 messages/minute: delay = 60000ms / 60 = 1000ms between messages.

    Characteristics:
    • Smooth, evenly distributed message processing over time
    • Predictable, constant throughput rate
    • Each message incurs the calculated delay before the next message is fetched
    • More suitable for steady-state workloads with consistent message arrival rates
    Example: With 100 messages/minute setting:
    • Delay between messages: 600ms
    • Processing pattern: message → 600ms delay → message → 600ms delay → ...
    • Exactly 100 messages processed per minute, evenly spaced
    Best for: Scenarios requiring smooth, predictable load distribution; preventing burst traffic to downstream systems; strict timing requirements.
  • BATCH: Processes messages in bursts up to the specified count within each time window, then waits until the next time window begins. Messages are consumed rapidly until the batch limit is reached, followed by a pause until the time window resets.

    Characteristics:
    • Bursty processing pattern with idle periods
    • Processes messages as fast as possible until limit reached
    • After reaching count limit, waits for the time window to reset before processing more
    • More efficient for scenarios where downstream systems can handle bursts
    Example: With 100 messages/minute setting:
    • At minute start (0:00): rapidly process 100 messages (may take 5-10 seconds)
    • Remaining time (0:10 - 1:00): idle, waiting for next time window
    • At next minute (1:00): process next 100 messages
    Best for: Batch-oriented downstream systems; scenarios where burst processing is acceptable; maximizing throughput within rate limits while minimizing overall processing time.

    Default and recommended: BATCH mode is simpler and typically more efficient, as it minimizes the overhead of per-message delays while still respecting rate limits.
Mode comparison:
Aspect FIXED_INTERVAL BATCH
Processing pattern Evenly distributed over time Bursty with idle periods
Downstream load Smooth, constant rate Burst at window start, then idle
Latency More consistent per-message Variable (fast if within limit, delayed if limit reached)
Efficiency Lower (constant delay overhead) Higher (processes at max speed within limits)
Best for Steady load distribution, timing-sensitive operations Burst-tolerant systems, maximizing throughput

Important: Only relevant when rabbitmq.throttle.enabled is true. The mode selection depends on downstream system characteristics and processing requirements.
No BATCH
rabbitmq.throttle.timeUnit Throttling Time Unit Defines the time window for applying the throttling rate limit. Combined with rabbitmq.throttle.count, this determines the maximum message processing rate. Options:
  • MINUTE: Rate limit is applied per 60-second window. The throttle count represents the maximum messages to process per minute.

    Use cases:
    • Short-term rate limits (typical for most API rate limits)
    • Fine-grained control over processing rates
    • Responsive throttling that adapts quickly to load changes
    Example: count=120, timeUnit=MINUTE → Maximum 120 messages per minute (2 messages/second average)

    FIXED_INTERVAL behavior: 60000ms / 120 = 500ms delay between messages
    BATCH behavior: Process up to 120 messages rapidly, then wait until next minute boundary
  • HOUR: Rate limit is applied per 60-minute window. The throttle count represents the maximum messages to process per hour.

    Use cases:
    • Hourly API quotas or service limits
    • Longer-term resource management
    • Systems with hourly billing or cost tracking
    Example: count=10000, timeUnit=HOUR → Maximum 10,000 messages per hour (≈167 messages/minute average)

    FIXED_INTERVAL behavior: 3600000ms / 10000 = 360ms delay between messages
    BATCH behavior: Process up to 10,000 messages rapidly at hour start, then wait until next hour
  • DAY: Rate limit is applied per 24-hour window. The throttle count represents the maximum messages to process per day.

    Use cases:
    • Daily quotas or processing limits
    • Long-term capacity planning and cost control
    • Systems with daily budget constraints
    • Compliance requirements with daily processing caps
    Example: count=100000, timeUnit=DAY → Maximum 100,000 messages per day (≈4167 messages/hour, ≈69 messages/minute average)

    FIXED_INTERVAL behavior: 86400000ms / 100000 = 864ms delay between messages
    BATCH behavior: Process up to 100,000 messages rapidly at day start, then wait until next day (midnight)
Choosing the right time unit:
  • Match downstream limits: If external API has 1000/hour limit, use HOUR with count=1000
  • Consider bursty behavior: Shorter time units (MINUTE) with BATCH mode create more frequent bursts; longer units (HOUR, DAY) create larger, less frequent bursts
  • Balance responsiveness: Shorter time units allow faster adaptation to changing conditions
  • Account for time zone resets: DAY-based throttling resets at midnight in the system timezone
Important: Only relevant when rabbitmq.throttle.enabled is true. The time unit should align with the rate limiting requirements of your downstream systems or organizational policies.
No MINUTE
rabbitmq.throttle.count Throttling Limit Specifies the maximum number of messages to process within the configured time unit. Combined with rabbitmq.throttle.timeUnit, this defines the target processing rate.

How it works: The count determines either:
  • FIXED_INTERVAL mode: Used to calculate the delay between messages: delay = (timeUnit in milliseconds) / count
  • BATCH mode: The maximum number of messages to process before waiting for the next time window
Calculation examples:
  • count=60, timeUnit=MINUTE → 60 messages per minute = 1 message/second
    • FIXED_INTERVAL: 1000ms delay between messages
    • BATCH: Process 60 messages, wait until next minute
  • count=3600, timeUnit=HOUR → 3600 messages per hour = 1 message/second
    • FIXED_INTERVAL: 1000ms delay between messages
    • BATCH: Process 3600 messages, wait until next hour
  • count=10, timeUnit=MINUTE → 10 messages per minute = 1 message every 6 seconds
    • FIXED_INTERVAL: 6000ms delay between messages
    • BATCH: Process 10 messages rapidly, wait ~50+ seconds until next minute
Setting appropriate values:
  • Match external limits: If calling an API with 1000 requests/hour limit, set count to slightly below (e.g., 950) to provide safety margin
  • Consider processing time: Ensure the count allows enough time for actual message processing. For BATCH mode, count × avg_processing_time should be less than the time window
  • Account for multiple consumers: If multiple consumer instances are running, divide the total limit by the number of instances
  • Start conservative: Begin with lower counts and gradually increase based on monitoring and downstream system capacity
Impact on throughput:
  • Lower counts: More restrictive throttling, lower throughput, higher queue backlog risk, but better downstream protection
  • Higher counts: Less restrictive throttling, higher throughput, faster queue processing, but may stress downstream systems
Monitoring considerations:
  • Monitor queue depth to ensure throttling limits aren't causing excessive backlog
  • Track actual processing rates to verify throttling is working as expected
  • Alert on queue growth that exceeds normal thresholds
  • Adjust count dynamically based on downstream system health and capacity
Important: Required when rabbitmq.throttle.enabled is true. Must be a positive integer greater than 0. The effectiveness of throttling depends on proper alignment with downstream system capabilities and rate limits.
No -
Other
rabbitmq.server.virtual.host Virtual Host The virtual host (vhost) to connect to. Leave blank for the default '/' vhost. No /
rabbitmq.message.content.type Content-Type Specifies the default Content-Type header to apply to consumed messages when the content type cannot be determined from the message's properties.

How it works: RabbitMQ messages can include a content_type property set by the publisher. If this property is missing or empty, the connector uses this default value to interpret and process the message body appropriately.

Common values:
  • application/json: For JSON-formatted message bodies (most common for modern APIs and microservices)
  • application/xml: For XML-formatted message bodies
  • text/plain: For plain text messages
  • application/octet-stream: For binary data without specific format
  • application/x-www-form-urlencoded: For form-encoded data
Use cases:
  • Working with legacy systems that don't set content type properties
  • Enforcing a default format for all messages in a queue
  • Ensuring proper message deserialization when content type is ambiguous
Important: This value is only used as a fallback when the message doesn't have a content_type property. Messages with explicit content_type properties will use their own value. Leave blank if content type should always be determined from message properties (recommended when publishers consistently set this property).
No -
rabbitmq.message.content.encoding Content Encoding (Charset) Specifies the default character encoding/charset to use when decoding text-based message bodies if the encoding cannot be determined from the message's properties.

How it works: RabbitMQ messages can include a content_encoding property set by the publisher indicating the character set (e.g., UTF-8, ISO-8859-1). If this property is missing, this default value is used to decode the message body bytes into text.

Common values:
  • UTF-8: Universal character encoding supporting all languages (most common and recommended default)
  • ISO-8859-1 (Latin-1): Western European languages
  • US-ASCII: Basic ASCII characters only
  • UTF-16: Unicode encoding with 16-bit code units
Use cases:
  • Working with legacy publishers that don't set content encoding
  • Ensuring correct text decoding for international character sets
  • Preventing character corruption when processing multilingual messages
Considerations:
  • Incorrect encoding can cause character corruption, especially for non-ASCII characters (accents, emoji, non-Latin scripts)
  • UTF-8 is the safest default for modern applications as it supports all Unicode characters
  • This only affects text-based content types; binary data is not decoded
Important: This value is only used as a fallback when the message doesn't have a content_encoding property. Leave blank if encoding should always be determined from message properties (recommended when publishers consistently set this property).
No -
rabbitmq.queue.overflow.strategy Queue Overflow Strategy Defines the behavior when a queue reaches its maximum length limit (set via maxLength or maxLengthBytes). This setting adds the x-overflow argument to the queue declaration. Options:
  • DROP_HEAD: Automatically discards the oldest messages from the front of the queue to make room for new incoming messages. The queue maintains its maximum size by continuously dropping the oldest data. Publishers are not notified of the drops, and messages are silently discarded without any delivery guarantees. Best for scenarios where recent data is more valuable than old data, such as real-time metrics, live sensor readings, or recent activity feeds where historical data can be safely discarded.
  • REJECT_PUBLISH: Refuses to accept new messages when the queue is full. Publishers receive a negative acknowledgment (basic.return or exception depending on the client), allowing them to handle the rejection (retry, log error, route elsewhere). The queue preserves all existing messages without dropping any. Suitable for workloads where message loss is unacceptable and publishers can implement backpressure handling or alternative routing strategies.
  • REJECT_PUBLISH_DLX: Similar to REJECT_PUBLISH, but rejected messages are automatically routed to the configured Dead Letter Exchange (DLX) instead of being lost. This allows rejected messages to be captured, inspected, and potentially reprocessed later. Requires a DLX to be configured on the queue; otherwise, behaves like REJECT_PUBLISH. Ideal for critical workflows where overflow messages need preservation and manual review, or for implementing overflow queues as a secondary processing tier.
Use case guidance:
  • DROP_HEAD: Circular buffers, caching layers, monitoring dashboards, sliding time windows
  • REJECT_PUBLISH: Task queues with strict ordering, financial transactions, systems with explicit backpressure
  • REJECT_PUBLISH_DLX: Audit systems, compliance-sensitive workflows, overflow handling with recovery options
Important: This setting applies to CLASSIC and QUORUM queues when length limits are defined. STREAM queues handle overflow through their own retention mechanisms (maxAge, maxLengthBytes). This parameter is used when auto-declaring queues; for pre-existing queues, the overflow strategy must be set via queue arguments during queue creation.
No DROP_HEAD
rabbitmq.message.requeue.delay Requeue Delay Specifies the delay (in milliseconds) before a failed message is automatically requeued to the original queue for reprocessing.

How it works: When a message processing fails and the consumer negatively acknowledges it (nack) with requeue=true, instead of immediately returning the message to the queue, the connector waits for this delay period before requeuing. This prevents rapid retry loops and gives time for transient issues to resolve.

Use cases:
  • Transient failure handling: Temporary database connection issues, external service timeouts, rate limiting
  • Rate limiting: Preventing overwhelming of downstream services with rapid retries
  • Circuit breaker support: Allowing time for circuit breakers to reset or services to recover
  • Resource contention: Giving time for locks to release or resources to become available
Typical values:
  • 0-1000ms (0-1 second): Quick retry for very transient failures
  • 5000-10000ms (5-10 seconds): Moderate delay for service recovery
  • 30000-60000ms (30-60 seconds): Longer delay for persistent transient issues
Considerations:
  • During the delay, the message is held by the consumer and counts against the prefetch limit
  • Longer delays reduce retry storms but increase message processing latency
  • This is a simple fixed delay; for exponential backoff, consider using the FIXED_DELAY_RETRYABLE_DISCARD strategy with delay queues
  • If rabbitmq.auto.ack.enabled is true, this setting has no effect as messages are auto-acknowledged
Important: Leave blank or set to 0 for immediate requeue (no delay). This setting only applies when messages are nacked with requeue=true. For more sophisticated retry patterns with exponential backoff, use dead letter exchanges with TTL-based delay queues.
No -
rabbitmq.auto.ack.enabled Auto Acknowledge Enabled Controls whether messages are automatically acknowledged immediately upon delivery to the consumer, before processing begins.

Behavior:
  • false (default, recommended): Manual acknowledgment mode. Messages are acknowledged only after successful processing by the application. If processing fails or the consumer crashes, unacknowledged messages are automatically requeued by RabbitMQ, ensuring at-least-once delivery. Provides reliability and message safety at the cost of requiring explicit acknowledgment handling.
  • true: Automatic acknowledgment mode. RabbitMQ considers messages acknowledged as soon as they're delivered to the consumer, regardless of processing outcome. If the consumer crashes or processing fails after delivery, the message is lost permanently. Provides higher throughput and simpler code but risks message loss. Only use when message loss is acceptable.
Trade-offs:
Aspect Auto ACK (true) Manual ACK (false)
Reliability Low - message loss on failures High - at-least-once delivery
Performance Higher throughput Slightly lower (ACK overhead)
Code complexity Simpler (no ACK handling) More complex (explicit ACK/NACK)
Message reprocessing Not possible Automatic on failure

When to use auto ACK (true):
  • Logs, metrics, or monitoring data where loss is acceptable
  • Duplicate-sensitive workflows where at-most-once delivery is required
  • High-throughput scenarios where performance outweighs reliability
  • Development/testing environments
When to use manual ACK (false, recommended):
  • Financial transactions, orders, payments, or any critical business data
  • State changes that must not be lost
  • Production systems where message reliability is important
  • Scenarios requiring retry on failure
Important: When auto ACK is enabled, settings like rabbitmq.message.requeue.delay, rabbitmq.ack.wait.time, and dead letter strategies have reduced or no effect since messages are acknowledged before processing.
No false
rabbitmq.ack.wait.time ACKNOWLEDGE Wait Time (ms) Defines the maximum time (in milliseconds) to wait for message processing to complete before timing out the acknowledgment operation.

How it works: In manual acknowledgment mode (rabbitmq.auto.ack.enabled=false), after delivering a message to the consumer application, the connector waits up to this duration for the application to process the message and send an acknowledgment (ACK or NACK). If processing exceeds this timeout, the connector may take timeout action depending on implementation (typically logging an error and potentially nacking the message).

Purpose:
  • Prevents indefinite blocking when message processing hangs or takes unexpectedly long
  • Allows detection of slow or stuck message processing
  • Ensures system responsiveness and resource cleanup
  • Helps identify performance bottlenecks or processing issues
Typical values:
  • 30000-60000ms (30-60 seconds): For quick processing tasks (API calls, simple transformations)
  • 180000ms (3 minutes): Default - suitable for moderate processing complexity
  • 300000-600000ms (5-10 minutes): For complex processing, external service calls, or batch operations
  • 900000ms+ (15+ minutes): For very long-running tasks, though these may be better handled asynchronously
Considerations:
  • Should be longer than your worst-case expected processing time plus buffer
  • Too short: legitimate long-running tasks may timeout and be requeued unnecessarily
  • Too long: hung processes won't be detected promptly, tying up resources
  • Monitor actual processing times to tune appropriately
  • Consider breaking very long tasks into smaller chunks or using async patterns
Important: This setting only applies when rabbitmq.auto.ack.enabled=false (manual acknowledgment mode). In auto ACK mode, messages are acknowledged immediately upon receipt, so this timeout is not relevant. Timeout behavior may vary by connector implementation - consult specific connector documentation.
No 180000
rabbitmq.concurrent.consumers.count Concurrent Consumers Specifies the number of concurrent consumer instances to create for processing messages from the queue in parallel.

How it works: Each consumer runs independently and can process messages simultaneously. RabbitMQ distributes messages across all active consumers using round-robin (by default) or other distribution strategies. Multiple consumers enable parallel processing and higher throughput.

Benefits of multiple consumers:
  • Increased throughput: Process more messages per second by parallelizing work
  • Better resource utilization: Keep CPUs busy while waiting on I/O operations
  • Fault tolerance: If one consumer fails, others continue processing
  • Reduced latency: Messages don't wait in queue as long when more consumers are available
Typical values:
  • 1: Single consumer - simplest configuration, ordered processing, lower throughput
  • 2-10: Moderate parallelism - good balance for most workloads
  • 10-50+: High parallelism - for high-volume queues or I/O-bound processing
Considerations:
  • Message ordering: Multiple consumers break message ordering within the queue. If strict ordering is required, use 1 consumer or implement application-level ordering
  • Resource consumption: Each consumer uses memory, threads, and connections. Scale based on available resources
  • Prefetch interaction: Works with rabbitmq.consumer.initial.credit (prefetch). Total in-flight messages = consumers × prefetch
  • Thread pool sizing: Should coordinate with rabbitmq.message.receiver.thread.pool.size - thread pool should be ≥ concurrent consumers
  • Bottleneck identification: If processing is CPU-bound, more consumers help. If I/O-bound (databases, APIs), many consumers increase parallelism
Scaling guidance:
  • Start with 2-4 consumers and monitor queue depth and processing latency
  • Increase if queue depth grows despite available CPU/memory
  • Decrease if consumers are often idle or resource usage is excessive
  • For I/O-bound tasks, can use more consumers than CPU cores
  • For CPU-bound tasks, match consumer count to available cores
Important: Changes require application restart to take effect. For dynamic scaling based on queue depth, consider using RabbitMQ autoscaling features or container orchestration (Kubernetes HPA).
No 1
rabbitmq.message.receiver.thread.pool.size Message Receiver Thread Pool Size Defines the size of the thread pool dedicated to receiving and initially processing messages from RabbitMQ. This thread pool handles message delivery from the broker to the consumer application.

How it works: RabbitMQ client libraries use threads to handle network I/O and message delivery. This parameter controls how many threads are available for these operations, enabling concurrent message receipt and processing.

Relationship with concurrent consumers:
  • Thread pool size should generally be greater than or equal to concurrent consumer count
  • Each consumer may use one or more threads from this pool
  • Insufficient threads can bottleneck message delivery even if consumers are idle
  • Recommended: thread pool size ≥ concurrent consumers (often 1.5-2× concurrent consumers)
Typical configurations:
Concurrent Consumers Recommended Thread Pool Size Rationale
1 1-2 Minimal overhead
5 5-10 1-2 threads per consumer
10 15-20 Buffer for peak loads
20+ 30-50+ High concurrency workloads

Considerations:
  • Too small: Message delivery bottleneck, consumers starved of messages, reduced throughput
  • Too large: Excessive memory usage (each thread consumes stack memory), potential thread contention
  • I/O-bound vs CPU-bound: I/O-bound processing benefits from larger thread pools; CPU-bound may not
  • Memory impact: Each thread typically uses 1MB+ of stack space (platform-dependent)
Tuning guidance:
  • Start with thread pool = 2 × concurrent consumers
  • Monitor thread utilization and message delivery latency
  • Increase if thread pool exhaustion is observed (blocked message delivery)
  • Decrease if excessive idle threads or memory pressure occurs
Important: This controls the connector's internal threading, not the application's business logic thread pool. Business logic may run on separate threads or executors depending on the connector implementation.
No 1
rabbitmq.consumer.initial.credit Consumer Initial Credit Defines the prefetch count (QoS - Quality of Service) limit, controlling the maximum number of unacknowledged messages that can be delivered to a single consumer at once.

How it works: RabbitMQ uses a credit-based flow control mechanism. Each consumer is allocated an initial credit (prefetch count). The broker delivers messages up to this limit before pausing delivery. As the consumer acknowledges messages, credit is replenished and more messages are delivered. This prevents consumers from being overwhelmed with messages.

Impact on system behavior:
  • Load balancing: With multiple consumers, lower prefetch ensures more even distribution (each consumer gets fewer messages at once). Higher prefetch may cause uneven load (fast consumers get many messages, slow ones get few)
  • Throughput: Higher prefetch increases throughput by reducing round-trips to the broker and keeping consumers continuously busy
  • Latency: Lower prefetch reduces message latency (messages don't wait in consumer buffers as long)
  • Memory usage: Higher prefetch increases consumer memory usage (more messages buffered in-flight)
  • Failure impact: Higher prefetch means more messages are redelivered if consumer crashes (all unacknowledged messages)
Typical values:
  • 1: Strict round-robin distribution, minimal memory, highest latency, lowest throughput. Best for ensuring fair load distribution or when message processing is very slow and inconsistent
  • 10-50: Balanced approach - good throughput with reasonable memory usage and load distribution. Suitable for most workloads
  • 100-1000: High throughput scenarios where consumers can handle large batches efficiently. Best when processing time is consistent and fast
  • 0 (unlimited): No limit - broker sends all available messages. Risky - can cause out-of-memory errors. Only for specific scenarios with known bounded queue sizes
Calculation with multiple consumers:
  • Total in-flight messages = concurrent consumers × prefetch count
  • Example: 5 consumers × 20 prefetch = 100 messages in-flight maximum
  • Ensure total doesn't exceed available memory and processing capacity
Tuning guidance:
Scenario Recommended Prefetch
Variable processing time (some messages slow, some fast) 1-10 (ensures fair distribution)
Consistent fast processing (< 100ms per message) 50-100 (maximize throughput)
I/O-bound processing (API calls, database queries) 20-50 (balance parallelism and memory)
Large messages (MB+ size) 1-5 (limit memory consumption)
Critical ordering requirements 1 (with 1 consumer)

Important: This is a per-consumer setting. Each consumer gets this prefetch limit independently. For auto-ack mode (rabbitmq.auto.ack.enabled=true), prefetch still applies but has less impact since messages are immediately acknowledged upon delivery.
No 1
rabbitmq.classic.override.requeue.with.discard Override Requeue Decision With Discard For Classic Queues: controls whether requeue attempts for failed messages are overridden and converted to discard/dead-letter operations instead.

Behavior:
  • false (default): Normal requeue behavior - when a message is negatively acknowledged (nack) with requeue=true, it is returned to the queue for redelivery. The message can be reprocessed by the same or different consumer.
  • true: Override mode - any requeue attempt (nack with requeue=true) is converted to a discard operation. Instead of returning to the queue, the message is:
    • Routed to the configured Dead Letter Exchange (if rabbitmq.dead.letter.exchange.name is set)
    • Discarded entirely if no DLX is configured
    This effectively disables requeuing for the queue, forcing all failed messages to follow the dead letter path.
Use cases for enabling (true):
  • Prevent infinite loops: When messages consistently fail and requeuing causes endless retry cycles
  • Poison message protection: Immediately route problematic messages to DLQ for inspection rather than reprocessing
  • Enforce dead letter workflow: Ensure all failures go through the dead letter mechanism for consistent handling
  • Debugging and monitoring: Capture all failed messages in DLQ for analysis without reprocessing noise
  • Complement to delivery limits: Work with delivery limit settings to ensure messages don't cycle indefinitely
Relationship with other settings:
  • Works in conjunction with rabbitmq.classic.dead.letter.strategy
  • Requires rabbitmq.dead.letter.exchange.name to be configured for failed messages to be captured (otherwise they're lost)
  • Interacts with rabbitmq.message.requeue.delay - when override is enabled, the delay is bypassed as messages aren't requeued
  • Most useful with NON_RETRYABLE_DISCARD strategy for immediate failure handling
Considerations:
  • Message loss risk: If DLX is not configured and this is true, all requeue attempts result in permanent message loss
  • No retry opportunity: Transient failures that might succeed on retry will instead be dead-lettered immediately
  • Monitoring importance: Essential to monitor DLQ when this is enabled, as all failures accumulate there
Example scenarios:
Setting Message Processing Fails Consumer Action Result
false (default) Consumer nacks with requeue=true Request requeue Message requeued for retry
true Consumer nacks with requeue=true Request requeue Message discarded/dead-lettered (requeue overridden)
true or false Consumer nacks with requeue=false Request discard Message discarded/dead-lettered (same behavior)

Important: This setting only applies to CLASSIC queue types and is ignored for QUORUM and STREAM queues. Always configure a Dead Letter Exchange when enabling this to prevent message loss. This is a safety mechanism - use with caution and ensure DLQ monitoring is in place.
No false