← Back to glossary

Message Ordering Guarantees

Messaging Intermediate

debt(d9/e5/b7/t7)

d9 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'silent in production until users hit it' (d9). The detection_hints field explicitly states 'automated: no'. Ordering violations surface only when real data flows through in production — e.g., a refund processed before a payment, or an update before a create — which are business-logic bugs invisible to compilers, linters, or static analysis tools.

e5 Effort Remediation debt — work required to fix once spotted

Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix prescribes using entity ID as partition key, limiting consumer count to partition count, and switching queue types (e.g., SQS FIFO). These changes span producer configuration, consumer configuration, and potentially infrastructure/queue topology — more than a single-line patch but not a full architectural rework.

b7 Burden Structural debt — long-term weight of choosing wrong

Closest to 'strong gravitational pull' (e7). The choice of ordering strategy shapes every producer (partition key selection), every consumer (parallelism constraints), and infrastructure decisions (queue type, partition count). Both common_mistakes and applies_to (cli, queue-worker) show this affects multiple system layers. Every future message type or consumer addition must respect the established ordering model.

t7 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'serious trap (contradicts how a similar concept works elsewhere)' (t7). The misconception is canonical: developers assume Kafka provides global ordering (as database transactions or single queues do), but it only guarantees order within a partition. This directly contradicts intuitions formed from simpler queue systems. The common_mistakes confirm multiple distinct variants of this trap across Kafka, RabbitMQ, and SQS.

About DEBT scoring → scored by claude-sonnet-4-6 · 2026-05-10 · reviewed by human

TL;DR

Message ordering is only guaranteed within a single Kafka partition or RabbitMQ queue — multiple partitions or consumers break FIFO order across the full topic.

Explanation

Kafka: messages within a partition are strictly ordered (by offset). Messages across partitions are not ordered. Partition key determines partition — same key = same partition = ordered. Consumer group with one consumer per partition = ordered processing. Multiple consumers on one partition: not supported (1 consumer per partition max). RabbitMQ: single queue = FIFO within the queue. Multiple consumers on one queue = no ordering. Priority queues alter order. SQS Standard: no order guarantee. SQS FIFO: ordered within a message group, limited throughput. For ordering across entities: use the entity ID as the partition/group key.

Common Misconception

✗ Kafka guarantees global message ordering — it only guarantees order within a partition. For global ordering, use a single partition (kills parallelism).

Why It Matters

Incorrect assumptions about ordering cause processing of 'update' before 'create', or refund before payment — subtle but critical bugs in financial and order systems.

Common Mistakes

Using round-robin partition assignment for order-sensitive messages — breaks sequencing.
Multiple RabbitMQ consumers on an ordered queue — no longer FIFO.
SQS Standard for ordered processing — use FIFO queues.

Code Examples

✗ Vulnerable

// Random partition — order.updated may arrive before order.created:
$producer->produce(RD_KAFKA_PARTITION_UA, 0, $message, null); // Random partition

✓ Fixed

// Same key = same partition = ordered:
$producer->produce(RD_KAFKA_PARTITION_UA, 0, $message, $orderId); // Order by key

// Kafka: max 1 consumer per partition for ordering:
// consumer group size ≤ partition count

References

https://kafka.apache.org/documentation/#intro_topics