A worker receives a message, writes a record, and crashes before its acknowledgment reaches the server. When another worker sees the message again, has the system duplicated the business event? Not necessarily. NATS JetStream separates stored messages from delivery attempts and acknowledgments, and a precise translation should preserve those distinctions rather than smoothing them into a reassuring but false promise.
This guide explains NATS JetStream streams, durable consumers, PubAck, AckWait, MaxDeliver, redelivery, acknowledgment policies, stream retention, Nats-Msg-Id deduplication, and the difference between at-least-once message delivery and exactly-once business processing. It is for technical translators, global engineering teams, documentation writers, students and operators who need accurate language for JetStream documentation and troubleshooting.
Our example follows a fictional international learning platform publishing synthetic course-enrolment events. We never use live student records. The reader will trace each event from publication to stream storage, consumer delivery, application processing, acknowledgment and eventual retention expiry. Specific APIs and defaults must be checked against the deployed NATS version; this article teaches the distinctions that remain useful across versions.
Quick answer: no single green tick proves completion
Core NATS delivers live publish-subscribe messages; JetStream provides stored streams and tracked consumers. A successful PubAck is a storage-layer response. A consumer acknowledgment is the consumer’s declaration that a delivery has been handled. A database commit, notification send or payment capture is another independent result. Translating all of them as ‘delivered successfully’ destroys the information an incident responder needs. The useful sentence names the system component, the observed event and its evidence.
Walkthrough: one enrolment, two attempts
At 09:00 UTC a producer publishes synthetic event E17 to an enrolment subject captured by stream EVENTS. The server reports stream sequence 381. Consumer REGISTRAR sends the message to worker A. Worker A commits its database update but loses connectivity before the acknowledgment is recorded. After the configured wait, worker B receives another delivery of the same stream message. If both workers use E17 as an idempotency key, the second attempt can discover the completed update and avoid repeating it. Without that application logic, the business action might occur twice even though only one event was intended.
Translate the timeline, not just the noun
Put the timeline in a consistent timezone and show whether each timestamp came from the producer, server, consumer or external service. A stream sequence describes storage position; an event identifier describes the business occurrence; a delivery attempt number describes work being retried. A localization that merges those three values into a ‘message number’ cannot reliably explain why one event generated two log lines. Preserve missing evidence as ‘unknown’, never convert it into zero or an assertion that the action did not occur.
A practical glossary of JetStream state, limits and translation decisions
1. Core NATS versus JetStream
Core NATS delivers messages to currently active subscribers whereas JetStream can store messages for later delivery. This distinction decides whether a missed event is replayable at all.
Common translation error: Do not describe every NATS publish as a saved event. Clear wording: “Core NATS routes live messages; the named JetStream stream stores matching publishes.”
What to check: Verify the configured stream and its captured subject patterns. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
2. Subject names
A NATS subject is the dot-separated address that publishers and subscribers use to route messages. Its precise characters are operational syntax, not decoration.
Common translation error: A translated subject may no longer match subscriptions. Clear wording: “The event was published to the enrolment.created subject.”
What to check: Keep command tokens unchanged and translate their meaning alongside them. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
3. Wildcards
The single-token * wildcard differs from the trailing > wildcard that matches a hierarchy of subject tokens. Matching rules directly shape stream capture.
Common translation error: Calling both wildcards universal can include or exclude real records. Clear wording: “The stream captures subjects matching the stated pattern.”
What to check: Test several matching and nonmatching subject names. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
4. Stream configuration
Streams bind subject patterns to server-side storage together with retention, replica and resource settings. There is no universal persistence promise without examining that configuration.
Common translation error: A subject being active does not prove a stream stores it. Clear wording: “The configured stream accepted this subject into storage.”
What to check: Read the stream configuration and publish response. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
5. Stream sequence
A stored message receives a sequence within its named stream. It identifies a position in stored history, not a worldwide business event number.
Common translation error: Do not use it as an external transaction ID. Clear wording: “This event was stored as stream sequence 381.”
What to check: Record stream name, sequence and business identifier separately. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
6. Publish acknowledgment
The JetStream PubAck describes a server-side publish result and can include the stored sequence. It says nothing about completion of a consumer’s business operation.
Common translation error: A green publisher response is not an email delivery receipt. Clear wording: “The stream acknowledged publication of the event.”
What to check: Compare PubAck with downstream application logs. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
7. Publisher retries
A producer may retry after a timeout when the first response is uncertain, even if the original write succeeded. Retries can be normal recovery behavior.
Common translation error: Do not automatically count retries as new enrolments. Clear wording: “The publisher retried because confirmation was uncertain.”
What to check: Correlate request IDs with stored stream records. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
8. Nats-Msg-Id
The publisher-supplied Nats-Msg-Id header participates in duplicate detection during a configured interval. It does not replace a permanent application idempotency key.
Common translation error: Deduplication is not permanent across all history. Clear wording: “Matching publish identifiers are deduplicated inside the configured window.”
What to check: Inspect the header and duplicate-window setting. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
9. Deduplication window
JetStream duplicate recognition is time-bounded. A late retry may create another stored record even when an early retry was suppressed.
Common translation error: Never translate deduplication as lifelong exactly-once processing. Clear wording: “The broker recognizes repeated identifiers within its window.”
What to check: Test simulated retries on either side of the boundary. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
10. Business event identity
An application’s event ID, stream sequence and delivery-attempt number are different identifiers serving different purposes. Mixing them makes incident reconciliation impossible.
Common translation error: A second delivery is not necessarily a second business action. Clear wording: “Event E17 had two consumer delivery attempts.”
What to check: Join logs on stable business and stream identities. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
11. LimitsPolicy
Limits-based retention keeps stored messages subject to age, count and size restrictions, regardless of whether a particular consumer has acknowledged them.
Common translation error: An acknowledgment does not necessarily erase stream data. Clear wording: “The record remains subject to configured storage limits.”
What to check: Inspect retention mode and its three major bounds. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
12. InterestPolicy
Interest retention considers eligible consumers’ interest and acknowledgments while remaining subject to stream limits. Consumer lifecycle matters when describing retention.
Common translation error: Do not equate one reader’s acknowledgment with universal deletion. Clear wording: “Retention follows configured consumer interest and acknowledgment rules.”
What to check: Inspect interested consumers and stream limits. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
13. WorkQueuePolicy
Work queue retention supports work distribution and removal on acknowledgment according to its constraints. It is not the same as independent fan-out to many competing filtered consumers.
Common translation error: A work queue is not a generic broadcast archive. Clear wording: “Eligible work is removed after the relevant acknowledgment.”
What to check: Check overlap restrictions on consumer subject filters. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
14. MaxMsgs
A count limit places an upper bound on how many stored messages a stream retains. Traffic spikes can make a count-based history period very short.
Common translation error: A count is not a duration of archival coverage. Clear wording: “The stream is configured with a message-count cap.”
What to check: Compare peak publish rate with earliest retained sequence. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
15. MaxBytes
Byte limits apply to stored data volume, not automatically to a number of logical business transactions. Large payloads can exhaust capacity quickly.
Common translation error: Do not translate bytes into records without measurement. Clear wording: “Stored history also has a byte-size ceiling.”
What to check: Inspect actual payload sizes and stream storage use. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
16. MaxAge
Age-based retention determines how long messages are eligible to remain stored. The age limit does not ensure workers process the event by that time.
Common translation error: A seven-day store is not a seven-day resolution SLA. Clear wording: “Messages exceeding the configured age can expire from storage.”
What to check: Check current MaxAge and observed historical availability. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
17. DiscardOld
When a stream reaches a limit under a discard-old policy, older stored messages may make way for new events. This can surprise late replay consumers.
Common translation error: Do not claim new writes always fail at capacity. Clear wording: “New records can displace older retained messages.”
What to check: Inspect the discard policy and stream sequence range. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
18. DiscardNew
A discard-new policy can refuse additional publishes when the stream cannot accept them within configured limits. The rejection is a write-side result.
Common translation error: Do not blame consumers for a rejected producer publish. Clear wording: “The stream rejected the new event under its limits.”
What to check: Read the publish error and storage configuration. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
19. File storage
File-backed JetStream storage uses disk-based persistence according to its configured durability and replication mechanisms. It is still bounded by resource and retention policies.
Common translation error: File storage is not infinite, immutable legal archiving. Clear wording: “The stream uses file storage under its stated limits.”
What to check: Inspect storage type, replicas, backups and capacity. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
20. Memory storage
Memory-backed streams have different resource and restart characteristics from file-backed streams. Choosing storage type changes how the system should be described.
Common translation error: Avoid calling an in-memory stream a permanent archive. Clear wording: “The stream uses memory-backed storage.”
What to check: Verify storage setting and failure expectations. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
21. Replica factor
Replicated JetStream streams can maintain copies on configured cluster members. Replica count does not itself specify geographic disaster recovery.
Common translation error: Three replicas do not automatically mean three countries. Clear wording: “The stream uses the configured replica factor.”
What to check: Inspect topology, fault domains and quorum requirements. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
22. Leader changes
Replicated streams can elect a new leader after failures. A temporary interruption in availability is different from proven permanent loss of stored events.
Common translation error: Do not translate a leadership change as deletion. Clear wording: “The stream leadership changed; availability was affected.”
What to check: Check cluster status and committed sequences. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
23. Durable consumers
A durable consumer keeps server-side progress across ordinary client restarts. The consumer’s state does not preserve all external work-in-progress details inside an application.
Common translation error: Consumer persistence is not universal transaction recovery. Clear wording: “This durable consumer retains its delivery position.”
What to check: Check state after a controlled client restart. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
24. Ephemeral consumers
Ephemeral consumers serve short-lived reading workflows and can be removed according to lifecycle behavior. A new reader may not inherit previous progress.
Common translation error: Do not promise durable resume for deleted ephemeral state. Clear wording: “This reader uses a short-lived consumer.”
What to check: Inspect consumer existence and starting position. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
25. Filtered consumers
Consumers can receive a filtered subset of stream subjects. Filtering controls delivery selection rather than secretly deleting unmatched records.
Common translation error: A filter is not a data deletion rule. Clear wording: “The consumer delivers only matching subjects.”
What to check: Compare the filter against the stream capture configuration. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
26. Pull consumers
A pull consumer lets workers request bounded deliveries when ready. Fetching does not necessarily acknowledge or remove the stored message.
Common translation error: Do not describe a fetch as completed processing. Clear wording: “The worker requested the next batch of deliveries.”
What to check: Check batch size, expiry and acknowledgment. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
27. Push consumers
A push consumer delivers eligible messages to a configured subject. This changes the data flow from client-requested to server-driven delivery.
Common translation error: Avoid saying every delivery begins with a client fetch. Clear wording: “The consumer pushes messages to the delivery subject.”
What to check: Inspect consumer delivery settings and subscriber availability. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
28. Deliver policy
The delivery policy decides the initial position for a new consumer, such as available history or a recent point. It does not manufacture expired records.
Common translation error: Reading from the beginning means available beginning, not all time. Clear wording: “This consumer starts at its configured available position.”
What to check: Compare initial policy with earliest retained sequence. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
29. AckExplicit
Explicit acknowledgment asks clients to confirm deliveries. A missing acknowledgment can lead to another attempt even if a side effect already occurred.
Common translation error: Receiving is not the same as acknowledging. Clear wording: “The worker acknowledged the processed delivery.”
What to check: Trace processing and ack events separately. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
30. AckNone
No-acknowledgment mode omits individual consumer confirmation. It suits workloads that accept its visibility and recovery tradeoffs.
Common translation error: Do not promise tracked completion under no-ack mode. Clear wording: “This consumer does not track explicit per-message acknowledgments.”
What to check: Inspect configured ack policy and intended workload. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
31. AckAll
An acknowledgment policy can cumulatively advance progress for eligible preceding deliveries. That is not independent evidence that each external action succeeded.
Common translation error: A cumulative ack is not a complete audit trail. Clear wording: “Acknowledgment advanced through earlier eligible deliveries.”
What to check: Check policy and out-of-order handling. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
32. AckWait
An acknowledgment deadline controls when unconfirmed work becomes eligible for redelivery. It is not a guaranteed time limit for finishing business operations.
Common translation error: Do not call AckWait the application’s maximum runtime. Clear wording: “Unacknowledged deliveries may be retried after the interval.”
What to check: Measure worker latency and configured AckWait. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
33. BackOff
Configured backoff can specify varying delays between delivery attempts. A single fixed delay in a translation may contradict the actual schedule.
Common translation error: A retry policy is not always one constant timeout. Clear wording: “Retries follow the consumer’s backoff settings.”
What to check: Inspect every configured backoff interval. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
34. MaxDeliver
MaxDeliver limits automatic consumer attempts under the policy. Exhaustion does not necessarily mean the stored record is purged or the business problem resolved.
Common translation error: Do not translate exhausted retries as successful disposal. Clear wording: “The consumer reached its configured attempt limit.”
What to check: Inspect advisories and stored-message availability. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
35. MaxAckPending
A consumer-wide limit caps outstanding unacknowledged messages and can throttle delivery across multiple workers. It is not the total stream capacity.
Common translation error: A slow consumer is not necessarily a full stream. Clear wording: “The consumer reached its unacknowledged-delivery limit.”
What to check: Compare limit with pending count and worker concurrency. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
36. Consumer pending metrics
Different pending metrics can refer to waiting messages or unacknowledged deliveries. A dashboard must name the precise field and measurement time.
Common translation error: ‘Pending’ without a qualifier can reverse meaning. Clear wording: “This metric counts the stated kind of outstanding work.”
What to check: Check the metric definition before interpreting a graph. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
37. Acknowledgment floor
The ack floor reflects contiguous acknowledged progress in a consumer’s state. It does not directly prove all downstream side effects were committed.
Common translation error: Do not use an ack floor as a business ledger. Clear wording: “Acknowledgment progress reached this stream position.”
What to check: Compare the floor with business records and gaps. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
38. Positive ack
A positive acknowledgment tells the server the consumer considers delivery handled. It is a transport-level fact and not an external receipt.
Common translation error: An ack is not a proof of delivery to a mailbox. Clear wording: “The consumer acknowledged the message.”
What to check: Check the external transaction independently. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
39. Negative ack
A negative acknowledgment indicates another delivery may be needed. It does not necessarily mean permanent failure or quarantine.
Common translation error: A retry request is not a dead-letter decision. Clear wording: “The worker negatively acknowledged an unsuccessful attempt.”
What to check: Observe subsequent deliveries and retry policy. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
40. In-progress ack
A progress signal can tell the server the worker is still active and needs more time. It is not the final processing acknowledgment.
Common translation error: Progress does not equal success. Clear wording: “The worker indicated ongoing processing.”
What to check: Check that a terminal outcome eventually occurred. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
41. Terminal ack
A terminal acknowledgment stops further automatic delivery attempts under the consumer’s semantics. Human investigation may still be required.
Common translation error: Do not equate stop-redelivery with issue fixed. Clear wording: “The consumer terminated further delivery attempts.”
What to check: Inspect advisory events and incident follow-up. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
42. Double acknowledgment
An acknowledgment confirmation round trip can establish that the server received and processed a consumer acknowledgment. It still does not make external side effects transactional.
Common translation error: ‘Double ack’ is not universal exactly once. Clear wording: “The server confirmed the consumer acknowledgment.”
What to check: Compare ack confirmation with downstream idempotency evidence. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
43. Redelivery count
The same stored event may be delivered more than once after uncertainty or a failure. Delivery count is not a count of unique real-world actions.
Common translation error: Do not count attempts as separate enrolments. Clear wording: “One event reached workers on several attempts.”
What to check: Compare stable message and attempt identifiers. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
44. Ordered consumers
An ordered reader serves inspection and ordered stream reading with distinct behavior from a durable shared work consumer. It is not a universal processing pattern.
Common translation error: Do not substitute an ordered reader for a work-queue worker. Clear wording: “This reader follows ordered inspection semantics.”
What to check: Check lifetime, ack behavior and restart assumptions. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
45. Replay pacing
Historical replay can proceed as quickly as possible or at another configured pace. A replay is not necessarily real-time recreation of original business effects.
Common translation error: Replaying events does not prove the past happened again. Clear wording: “The reader replays stored events under configured pacing.”
What to check: Compare original event times with delivery times. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
46. Purge and delete
An operator can purge stream data, unlike an ordinary consumer acknowledgment. The scope and authorization of deletion should be explicit.
Common translation error: An ack is not the same as a stream purge. Clear wording: “Stored messages were explicitly purged under an operator action.”
What to check: Record before-after state and authorized command. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
47. Mirrors
A mirror builds a stream based on an upstream stream. Its behavior depends on configuration and connectivity; it is not automatically synchronous disaster recovery.
Common translation error: Do not promise instant geographic duplication. Clear wording: “The stream mirrors its named upstream source.”
What to check: Test connectivity loss and restoration. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
48. Sources
A stream can aggregate records from several configured source streams. Resulting stored order should not be confused with one global business clock.
Common translation error: Aggregation is not a universal total order. Clear wording: “This stream incorporates records from named sources.”
What to check: Preserve source identity and event timestamps. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
49. Key-Value and Object Store
Higher-level JetStream-backed facilities expose specialized operations beyond ordinary message consumption. Their contracts should be described separately.
Common translation error: Do not treat object storage as a limitless event stream. Clear wording: “The application uses the named storage abstraction.”
What to check: Verify the specific API and size limits. Write down which observed component and exact time support the claim, especially when a sentence may be repeated in a global incident report.
What a safe incident sentence sounds like
Instead of ‘the message failed and was sent again’, write that the first consumer delivery was not acknowledged before its configured deadline and another delivery was observed. If the cause is unverified, say so. Instead of ‘data was lost’, distinguish a publish rejection, a stream retention eviction, an absent consumer, a deleted stream record and an unavailable replica. Those are different diagnoses, with different recovery options and different responsibilities.
When retention changes the truth
A queue and an archive serve different purposes. A limits-based stream can lose old data at its age, count or byte bounds while a slow consumer is still trying to catch up. Work-queue and interest-based retention have other rules. A reader who hears ‘stored safely’ may mistakenly assume permanent retention; a better explanation specifies stream policy, earliest available sequence and separate archival arrangements. Security and privacy language should also avoid equating consumer acknowledgment with universal erasure.
A bilingual configuration review
Keep literal API and configuration names intact: AckWait, AckExplicit, MaxDeliver, MaxAckPending, Nats-Msg-Id and subject patterns should survive translation unchanged. Explain them in the reader’s language immediately afterward. Preserve units such as bytes, milliseconds, seconds, message counts and replica counts. Never convert an ‘attempt’ into a ‘minute’ or a ‘replica’ into a physical region. Document whether a value is a local configuration or a vendor default, and verify defaults for the running release.
A small testing plan that checks claims
Use a nonproduction stream with synthetic records. Test a successful publication and acknowledgment, then simulate a worker crash after a side effect but before ack. Compare event ID, stream sequence, delivery count and external transaction state. Test one deliberately rejected publish and one consumer that falls behind retention. If a translated claim cannot be demonstrated in these scenarios, revise it from an absolute outcome to the observed, supported event.
The hidden difference between retry and duplication
A retry is an attempt to recover from uncertainty. A duplicate business effect is an application outcome. Two retries may produce only one stored stream record during a configured deduplication window, yet a separate consumer might still perform an external side effect twice. Conversely, multiple legitimate consumers may see the same stored message for independent jobs without constituting an error. The reader should learn to ask ‘duplicated at which layer?’ before drawing conclusions.
How to write for readers in different roles
An engineer needs exact configuration names, error conditions and state transitions. A support agent needs a short explanation of what was observed and what remains unverified. A manager needs the practical consequence: whether customer-facing work happened, might repeat or can be recovered. All three deserve the same underlying truth. Offer a short answer first, then the detailed mechanism, a worked example, and a testable action. The language can be simple without weakening the contract.
Separating NATS from adjacent systems
Redis Streams, RabbitMQ and JetStream can all coordinate messages but use different persistence, acknowledgment and consumer models. Avoid importing a term such as ‘pending entries list’ from a different product as though it were a native JetStream guarantee. A glossary can mention analogies for orientation, but the formal explanation must follow the actual NATS fields and documentation. This article owns the JetStream consumer and retention behavior, not a generic guide to every message broker.
A useful troubleshooting worksheet
Record the stream name, subject, retained sequence range, publish response, consumer identity, deliver policy, acknowledgment policy, maximum delivery attempts, pending counts and observed application effects. Add the exact time and the deployed server version. Then separate verified observations from hypotheses. If the stream accepted an event but no consumer received it, investigate filtering and consumer position before saying the message disappeared. If the consumer received it but the user saw no email, investigate the notification stage before blaming persistence.
Why the final wording matters
Translations outlive the incident that inspired them. A casual phrase can become a runbook instruction, a training handout or a customer guarantee. Words such as stored, dispatched, acknowledged, retried, completed and removed are not interchangeable labels. Requiring each word to correspond to observable evidence makes both the documentation and its translation useful when a system is under pressure.
Questions readers ask
Does JetStream guarantee exactly-once business work?
No. It provides storage, configurable delivery and publish deduplication mechanisms. External database writes, payments and notifications need their own idempotency and recovery safeguards. One stream sequence does not prove one downstream side effect.
Why might a consumer see the same message again?
A failed, delayed or uncertain acknowledgment may cause another delivery under the configured policy. Compare stream sequence, consumer identity and attempt metadata before counting unique business events.
Can an acknowledged message remain in a stream?
Yes. That depends on the stream’s retention model and resource limits. Acknowledgment advances consumer progress but does not universally delete stored data.
What does MaxDeliver mean?
It limits automatic delivery attempts for a consumer. It is not a universal deletion guarantee and does not itself prove that a downstream task succeeded.
Should identifiers be translated?
Preserve exact names for commands, subjects, headers and configuration fields. Translate the explanatory text around those names. The code tokens must remain usable.
How do I describe a suspected loss?
Identify whether the publisher was rejected, storage accepted the event, the consumer could see it and retention removed it. Use ‘not observed’ where evidence is incomplete instead of claiming permanent data loss.
Source documentation and neighboring reading
Official NATS JetStream concepts; JetStream stream, consumer and acknowledgment tutorial; pull-consumer reference. Continue with the Translate Like a Pro index and the separate Redis Streams guide. Verify deployment-specific settings before issuing commands.
Worked example: confirming a publish while a consumer is offline
Suppose a producer publishes event E104 to a captured subject and receives a PubAck identifying stream COURSE_EVENTS and sequence 704. The durable consumer responsible for updating the catalogue has no connected workers. A correct report says the event was stored and that downstream processing is waiting; it must not say the catalogue was updated. On reconnect, a worker may read the stored event from the durable consumer’s available position, but that recovery is still bounded by retention and consumer configuration. The report should show three independent facts: the publish acknowledgment, the last consumer delivery observed, and the last external catalogue update committed. Translators should preserve the difference between a delayed action and a failed publish, because their remedies are entirely different.
A useful user-facing sentence would read: ‘We accepted the update for processing, but the catalogue display has not yet been confirmed.’ It communicates progress without promising a specific completion instant. If operators need evidence, point them to the stream sequence, durable consumer’s state, and downstream application’s transaction record. A synthetic test with the worker deliberately disconnected can demonstrate whether the intended catch-up behavior is actually available.
Worked example: a late producer retry after the duplicate window
Consider a producer that sends event E105 with Nats-Msg-Id set to E105 and then loses the connection before recording the server response. An immediate retry using the same identifier may be recognized by the stream within its configured duplicate window. But if the application retries long afterward, duplicate detection at this layer may no longer apply. The correct explanation cannot be ‘NATS guarantees one event forever’ or ‘every retry creates a duplicate’. Both are absolute claims unsupported by the time-bounded contract. Record the retry time, publish identifier, stream sequence and any duplicate indication in the server response.
Even if publish deduplication prevents a second stored record, the application must still consider consumer redelivery. The two kinds of repetition answer different questions: did the producer create multiple accepted records, and did a consumer attempt work more than once? For financial and user-facing actions, the receiving application should preserve a stable business key and check it at the point where side effects are committed.
Worked example: an acknowledgment deadline during slow work
A worker receives event E106 and begins a long-running document export. Its processing takes longer than the configured acknowledgment interval. Without a suitable progress mechanism or acknowledgment strategy, the server may make the message eligible for redelivery while the original worker is still active. Another worker can therefore receive the same stored event and start a second export. A translation saying ‘the first worker failed’ would not be supported merely by the retry. The more accurate statement is that the delivery remained unacknowledged at the deadline and another attempt became possible.
What should the application do? It can design the export around a stable job identifier, use supported in-progress signaling when applicable, and confirm one terminal outcome after durable completion. Translate those instructions as responsibilities of the consuming application, not as an unconditional guarantee of the broker. Test the actual processing duration and backoff configuration in a safe environment before describing expected retry timing to end users.
Worked example: limits retention and a slow audit reader
An audit application is temporarily offline. Meanwhile the stream continues receiving high-volume events and reaches a count-based or byte-based retention limit. With a discard-old policy, new events can displace older stored records. When the audit reader reconnects, it may encounter a gap in the history that remains available. A report should say which sequence range is accessible, identify the observed retention rule, and avoid claiming that missing records were never published. That distinction helps engineers decide whether to recover from an independent archive rather than debugging a producer that may have worked correctly.
For a world-facing reader, explain that a stream’s retention period is a storage policy, not a guarantee that every observer processes every event before expiry. If the organization’s obligation is to preserve a formal audit record, it needs a separate verified archival strategy appropriate to the data and local requirements. Consumer acknowledgments cannot by themselves prove that a record exists or has been erased in every external system.
Worked example: switching retention policies changes reader expectations
Three streams may carry the same kind of synthetic enrolment event but serve different purposes. A limits-policy stream supplies a replayable operational log bounded by age, size and count. A work-queue-policy stream supports shared work under its specific acknowledgment and filter constraints. An interest-policy stream responds to configured consumer interests and acknowledgments within other limits. A translator who describes all three as ‘a queue that deletes each event as soon as someone reads it’ has erased their core differences. The correct choice of verbs depends on each stream’s actual policy.
An operational table should show stream name, policy, maximum age, maximum messages, expected consumers, what counts as acknowledgment, and the evidence used to confirm retention. This table is more useful than a universal slogan about persistence. It also highlights a practical design question: is the stream intended to distribute work, provide replay, or preserve a separately managed record? Those aims cannot be conflated simply because all three involve stored messages.
Worked example: message processing versus user-visible success
A learner presses a button to request a course certificate. The application publishes an event; a worker reads it; the worker stores a generated certificate in object storage; a notification service tries to send a link. Which of those steps can a web interface truthfully call completed? It depends on the promise made to the learner. If the interface promises a certificate is ready to download, publication and consumer acknowledgment are insufficient: the file must exist and be accessible. If it promises only that the request was received, a confirmed acceptance at the appropriate application layer may suffice.
This is where careful translation meets product design. Phrases such as ‘request received’, ‘generation in progress’, ‘certificate available’ and ‘notification sent’ have different evidence requirements. Specify the actual state and avoid selecting one generic word for all statuses. An error message becomes useful when it identifies whether a retry is safe, whether a previous job can be resumed, and what the learner can do next without accidentally initiating a second request.
A cross-service comparison that prevents vocabulary collisions
Distributed event systems sometimes use similar English nouns for different contracts. Kinesis Data Streams organizes records by shards and shard-scoped sequence numbers; Google Cloud Pub/Sub tracks topic and subscription delivery with feature-specific acknowledgment semantics; Azure Event Hubs uses partitions, independent consumer groups and external checkpoints. JetStream has its own named streams, policies, consumer identities and acknowledgment operations. These articles teach adjacent problems rather than interchangeable configuration recipes.
When translating a migration guide, create one table for observed business outcomes and separate tables for each system’s implementation. Map what the reader needs to achieve—persistent acceptance, replay within retention, shared work, ordered processing or verified downstream effects—before mapping vocabulary. A term such as queue, acknowledgment or checkpoint cannot be transferred from one product to another without checking the new service’s precise contract. Similar-looking diagrams conceal important differences in filtering, retention, replication and failure recovery.
The practical conclusion
The best technical translation explains exactly what the system did, not what the reader hopes happened. In JetStream a published message may be stored, delivered, retried, acknowledged and retained under several independent rules. The application must account for downstream side effects separately. Once those distinctions become visible, a difficult distributed-systems incident becomes a sequence of questions that a global team can actually answer.