Cloud Integration JMS retries: Investigate a poison message without losing it
A malformed supplier message repeatedly fails in a manufacturer's integration queue while valid work still needs processing.
START HERE · NO PRIOR TOPIC KNOWLEDGE NEEDED
What it is. Why it matters.
A message queue holds work for later processing. A poison message repeatedly fails, potentially delaying other messages, so recovery must identify and correct the failing case.
Completely new to SAP?
Manufacturers use SAP to connect work such as buying components, recording inventory, planning production, shipping equipment and accounting for costs. SAP S/4HANA is an enterprise resource planning system: it connects these activities through shared business data.
SAP Business Technology Platform, or BTP, provides cloud services for applications, data and integration. A connection needs a route, an identity and permission to perform the intended task.
A transaction code, or t-code, is a shortcut to a task in classic SAP GUI. Fiori apps provide another way to work. Names and screens depend on the product and release; you do not need a live system to learn the concepts in this guide.

Scope and source-review notes
Scope and evidence
Source review by FAST SAP SOLUTIONS® editorial. This badge describes our editorial review; it does not represent SAP certification or independent endorsement.
SAP Cloud Integration JMS queue retry patterns and dead-letter capability. Availability, limits and dead-letter conditions depend on edition, adapter settings and failure type.
Documentation review on 14 November 2026 using official SAP sources and indexed official excerpts where full Help text was unavailable. Scope and service or release differences are explained in the lesson. All datasets, requests and checks are illustrative; no customer SAP runtime execution or measured results are claimed.
A MANUFACTURING EXAMPLE
Recover a supplier queue without endless retries
Find the repeatedly failing message
Read the example values
- Queue
- Invoice processing
- Message A
- Invalid supplier reference
- Retry result
- Same failure
- Later messages
- May be delayed
Words you’ll meet in this guide
- Backend
- The service or system doing the work behind an interface.
- Destination
- Named connection settings for another service.
- Credential
- Access information used to prove an identity.
- Subaccount
- A BTP scope for applications, services and access settings.
- HTTP
- The request-and-response protocol used by web applications and APIs.
- JMS
- Java Message Service: a standard messaging API used with supported queue services.
Preview the practical steps
SEE THE CONNECTION
See it in a simple example.
A small example to make the idea concrete.
Recover a supplier queue without endless retries
A malformed supplier message repeatedly fails in a manufacturer's integration queue while valid work still needs processing.
Preserve the message and establish why it keeps failing
A poison message is a queued message that repeatedly fails because the same input or processing condition remains invalid.
Understand what the sender acknowledgment actually proves
In the documented asynchronous pattern, an inbound flow persists the message through the JMS receiver adapter and returns HTTP 202 Accepted.
Worked case: an invalid supplier holds an invoice in repeated failure
Imagine queue INV_IN carrying invoices INV-7001, INV-7002 and INV-7003.
Recover a supplier queue without endless retries
A malformed supplier message repeatedly fails in a manufacturer's integration queue while valid work still needs processing.
Inspect the failed message, retry and exception design before replaying it or discarding evidence needed for controlled recovery.
| Reader | Business question | Evidence to carry forward |
|---|---|---|
| SAP developers and application teams supporting manufacturers | Recover a supplier queue without endless retries | Inspect the failed message, retry and exception design before replaying it or discarding evidence needed for controlled recovery. |
01 Preserve the message and establish why it keeps failing
A poison message is a queued message that repeatedly fails because the same input or processing condition remains invalid. In Cloud Integration, first identify the queue entry and its business reference, classify the error and check receiver state. Repeated retries are useful for temporary failures; they do not correct an unknown supplier, invalid schema or deterministic mapping defect. Deleting the entry removes work without explaining its business outcome. [1]
This tutorial is for integration operators and developers using the JMS adapter in SAP Cloud Integration. You need the relevant monitoring and queue access, the deployed flow version, a permitted view of the payload and an agreed receiver reconciliation method. JMS capabilities and limits depend on edition and runtime. The cited retry guide excludes basic edition from that documented storage option; confirm your current entitlement and adapter support. [1]
02 Understand what the sender acknowledgment actually proves
In the documented asynchronous pattern, an inbound flow persists the message through the JMS receiver adapter and returns HTTP 202 Accepted. A second flow consumes it through the JMS sender adapter and calls the receiver. The initial response acknowledges acceptance into that processing design; it is not confirmation that a business invoice or order was posted. [1]
If downstream processing fails, the retry mechanism can redeliver persisted work according to the configured behavior. Track the original business identity across those attempts. Monitoring IDs identify processing evidence, while the invoice reference identifies the intended business effect. A consumer can see several attempts for one business instruction. Count effects at the receiver rather than treating every attempt as a separate invoice. [1]
03 Worked case: an invalid supplier holds an invoice in repeated failure
Imagine queue INV_IN carrying invoices INV-7001, INV-7002 and INV-7003. INV-7001 references supplier V404, which is absent in the target company-code context. The receiver rejects it before posting. The next two invoices use valid suppliers. Whether later entries wait depends on the queue’s access and processing design; do not assume every queue serializes all business work in the same way.
The error for INV-7001 repeats unchanged. The investigation should establish whether V404 is a legitimate master-data key awaiting replication, an incorrect partner code requiring mapping, or a malformed input. Those causes need different corrections. Creating arbitrary master data just to clear the queue could produce an invoice against the wrong supplier.
| Business reference | Supplier | Expected business result |
|---|---|---|
| INV-7001 | V404 | Rejected until key or master data is corrected |
| INV-7002 | V100 | One posted invoice if permitted to process |
| INV-7003 | V200 | One posted invoice if permitted to process |
04 Capture queue, processing and receiver evidence together
Record the queue name, entry identifier where available, original business reference, first failure time, latest attempt, deployed consumer version and sanitized exception. Preserve access-controlled payload evidence before any correction or replay. Keep credentials and sensitive invoice details out of a general incident ticket; the ticket can point to an authorized evidence location.
Compare the actual receiver response and its business lookup. For INV-7001, establish that no invoice exists for the agreed external reference in the intended company code. A timeout creates a different uncertainty than an explicit pre-posting rejection. If the receiver may already have committed, resolve that before replay. Queue durability does not make an external business operation automatically idempotent.
05 Classify temporary, deterministic and uncertain outcomes
A temporary network outage can recover without altering the message. A deterministic validation error normally needs corrected content, mapping, configuration or prerequisite master data. An uncertain outcome occurs when the receiver might have committed but the response was lost. That third category requires reconciliation and duplicate prevention before another attempt.
In the fixture, a documented “supplier not found” response plus a receiver lookup showing no posted invoice supports a deterministic prerequisite failure. If a retry later times out after the supplier exists, reassess the outcome; the original classification does not apply forever. Record each material state change instead of assuming all attempts failed in the same way.
| Category | Example | Useful next action |
|---|---|---|
| Temporary | Receiver unavailable before processing | Restore connection and allow configured retry |
| Deterministic | Supplier key invalid in target context | Correct mapping/input or authorized master-data prerequisite |
| Uncertain | Timeout after request delivery | Query receiver by stable business key before replay |
| Resource-related | Payload repeatedly destabilizes worker | Investigate size/processing and supported blocked handling |
06 Read retry settings from the deployed adapter
The documented JMS retry pattern includes retry interval, exponential backoff and maximum retry interval controls. Inspect the effective deployed values and access type. Do not infer retry cadence from a design-time default or a different flow. A growing delay under backoff can explain why a corrected dependency is not followed by an immediate new attempt. [1]
Avoid repeatedly retriggering the inbound flow because the outbound consumer is failing. The original message may already be persisted. Resending it can create a second queued copy and later duplicate business work. SAP’s example corrects the outbound receiver configuration and allows the existing queued work to complete without redeploying the inbound producer. Adapt that principle to the actual supported recovery path. [1]
07 Do not confuse poison business data with automatic dead-letter conditions
The cited JMS retry guide describes an optional dead-letter behavior for Non-Exclusive access that blocks a message after specified worker-node crash behavior. That is not a general rule saying every invalid invoice moves to a dead-letter queue after a fixed number of business rejections. Other adapters can document different conditions and counts. [1] [2]
Check the JMS sender adapter version and its current documentation before using blocked or dead-letter recovery. A schema error handled as a normal processing exception may continue retrying under its configured policy rather than meeting a crash-related blocking condition. Design ownership and notification for unresolved business errors explicitly instead of relying on a threshold copied from another adapter.
08 Choose a correction path that preserves business identity
If V404 is a valid supplier awaiting authorized master-data setup, correct that prerequisite and retry the original message through the supported mechanism. If it is a partner identifier that should map to V100, repair the value mapping and verify the mapping context before allowing retry. If the payload itself is wrong, use the organization’s supported correction or replacement process and preserve the relationship between original and replacement work.
A replacement message should retain a stable external business identity or a documented supersession relationship. Merely changing an integration message ID does not prove that the receiver will avoid duplicate invoices. If a queue entry must be removed under the supported operating procedure, capture the approved disposition and replacement or cancellation evidence first. Deletion should be the final state transition of a reconciled case, not the diagnostic method.
09 Troubleshoot repeated failures without losing the causal evidence
Use the earliest meaningful exception and the current receiver state. Later symptoms such as queue growth can be consequences. Also compare recent mapping or master-data changes with failure onset; the same payload may fail only after a new flow version changes a target field.
In the supplier fixture, also compare the target organizational context. Supplier V404 could exist globally but be unavailable for the company code required by INV-7001. A lookup that proves only that a supplier name exists is insufficient. Record which target validation rejected the instruction, then repair that exact prerequisite through the authorized business process. This keeps an integration retry from masking a master-data scope error.
| Observation | Likely question | Next comparison |
|---|---|---|
| Same business validation on every attempt | What condition changes between retries? | Payload key, mapping and target prerequisites |
| Queue grows while receiver is down | Is retry behavior expected? | Availability, retry settings and resource limits |
| Accepted response, no invoice | Has the consumer completed? | Queued entry and outbound processing log |
| Timeout with possible receiver record | Could a commit already exist? | Receiver lookup by external reference |
| Message blocked | Which documented condition triggered it? | Adapter access type, exception and node evidence |
| Later work delayed | Does the processing design preserve order? | Queue access type and business dependencies |
10 Verify the recovered effect and the remaining queue
After correction, verify INV-7001 at two levels: the queued processing reaches its expected terminal state and exactly one intended receiver invoice exists for the external reference. Inspect supplier and company-code context as well as document existence. A posted document against V100 is wrong if V404 was intended to identify another supplier.
Check INV-7002 and INV-7003 separately. If their processing was delayed, confirm that each now has one expected result. If they had already completed under the queue’s design, do not replay them simply because INV-7001 was repaired. Reconcile the fixture as three business instructions, not as one bulk “retry everything” action.
Keep unresolved entries visible with owners and disposition. A zero queue count can result from successful processing, deletion or movement; it is not by itself proof that every invoice posted. Compare message disposition with receiver documents and preserve the result for the next shift.
11 Run controlled failure exercises before depending on recovery
For the positive case, temporarily make a harmless development receiver unavailable, restore it and confirm the persisted message completes once. For the deterministic negative case, use an intentionally invalid supplier fixture and verify that repeated attempts do not alter the payload or manufacture a business success. Observe the configured retry policy rather than promising a universal count.
For the uncertainty boundary, simulate or reason through a lost response after a receiver commit. Demonstrate lookup by a stable external key and the receiver’s duplicate-handling contract. Where the test receiver lacks idempotency, document that gap and implement a supported design before relying on automated replay.
What should closure say? Record original identity, failure category, correction, replay or retry method, queue disposition and receiver outcome. State whether the exercise was executed or only reviewed. The related idempotency and asynchronous-success lessons explain why durable acceptance and retry still require business reconciliation.
Related services and next steps
Primary sources
Found this useful?
Share this guide with your network, or leave a like.
Your like is saved in this browser.