tryMax(3) retrying a POST creates duplicate records when the first attempt timed out server-side

Direct Answers

1. Yes — generating a unique idempotency key per virtual user or iteration (via a feeder or session attribute) and sending it as a header is the accepted pattern, provided the server honours that header and deduplicates.
2. Yes — if the server cannot be changed to support idempotency keys, the only safe option is to keep non‑idempotent writes outside tryMax (or restrict retries to explicit transport‑level failures only).
3. No — tryMax does not expose a hook to inspect individual attempt outcomes beyond the embedded checks; retry decisions are based solely on whether the wrapped chain fails according to the supplied criteria.

Why Duplicates Occur

In Gatling 3.x, tryMax(n) retries the entire chain when the chain fails. A chain fails if any check inside it fails (e.g., status.is(201)) or if an exception (such as a client‑side timeout) is thrown. When the first POST /orders succeeds on the server but the response is lost (client timeout), the check never sees a 201, so the chain fails and tryMax re‑sends the POST. Because the endpoint is not idempotent and has no deduplication, the server persists a second order.

Recommended Mitigation: Idempotency Key

Generate a unique key (UUID) per virtual user or per iteration and add it as a header (e.g., Idempotency-Key). The server must recognise this header and suppress duplicate processing for the same key.

val idempotencyFeeder = Iterator.continually(Map("idempotencyKey" -> java.util.UUID.randomUUID.toString))

scn.feed(idempotencyFeeder)
  .exec(http("Create Order")
    .post("/orders")
    .header("Idempotency-Key", "${idempotencyKey}")
    .check(status.is(201)))

With this pattern, even if tryMax retries, the server sees the same key and treats the retry as a duplicate, preventing a second record.

When the Server Cannot Change

If you cannot modify the server to accept an idempotency key, do not wrap the non‑idempotent POST in tryMax. Instead, let the request fail and handle the failure at the scenario level (e.g., with exitHereIfFailed or a custom retry loop that only retries on transport‑level exceptions like io.gatling.http.client.engine.HttpException).

tryMax Hooks and Attempt Inspection

The DSL does not provide a callback or hook to distinguish "server succeeded but response lost" from a genuine failure. The retry decision is binary: the chain either passes all checks or it doesn’t. Any logic that requires inspecting the response body, headers, or timing of each attempt must be implemented outside tryMax (e.g., a manual loop with doWhile and session‑based state).

Verification Steps

1. Enable debug logging (logLevel = DEBUG) and observe the console: you will see the same POST sent multiple times when the first attempt times out after a 201.
2. Use a mock server (WireMock) that returns 201 but closes the connection before sending the body. Run the simulation with tryMax(3) and confirm the mock receives two identical POST bodies.
3. Add the idempotency‑key feeder and programme the mock to ignore duplicate keys. Verify only the first request is processed.
4. Remove tryMax from the POST chain and run the scenario; the request count should match the number of iterations, confirming no duplicate posts.

Assumptions and Version Notes

This behaviour applies to Gatling 3.x (tested up to 3.10). The DSL has not changed in this regard in recent minor releases. If you are on Gatling 2.x, the same principles apply but the syntax differs.