Your retry logic is correct and does nothing

A comment on one of my posts sat open as an issue for two weeks before I understood how bad the thing it described actually was.

The post was about an AI assistant missing the SQS trigger on a Lambda. Mads Hansen replied with a sentence I have not been able to unthink since: the trigger shape is the first contract, delivery and retry semantics are the second. Getting event.Records[0].body right tells you how to read a message. It tells you nothing about what happens when one of ten messages in a batch throws.

I filed it as issue #87. The first item on that list is a bug no code reviewer can catch by reading the code, because the code is fine.

The handler that is correct and does nothing

Here is a batch consumer. It is the shape you get if you read the AWS docs and follow them.

export const processOrders = async (event: { Records: { messageId: string }[] }) => {
  const batchItemFailures: { itemIdentifier: string }[] = [];
  for (const record of event.Records) {
    try {
      await handleOrder(record);
    } catch {
      batchItemFailures.push({ itemIdentifier: record.messageId });
    }
  }
  return { batchItemFailures };
};

Nine records succeed, one throws, and the handler reports exactly the one that failed. That is the entire point of a partial batch response: the nine that worked are deleted from the queue, the one that failed comes back on its own.

Except this handler does not do that, because whether anyone listens to that return value is not decided in this file. It is decided by the event source mapping. If FunctionResponseTypes on the mapping does not contain ReportBatchItemFailures, Lambda discards the array. The whole batch is marked failed. All ten records are redelivered, including the nine that already ran to completion.

The failure mode is duplicate processing. Nine orders get handled twice, or twenty times, because one poison message keeps replaying its batch until the queue's retry limit. If your handler is not idempotent, that is double-charged customers, not a log line.

Why nobody catches this in review

Read that handler again with a critical eye. There is nothing wrong with it. It builds the array correctly, it uses messageId as the identifier, it catches per record rather than around the loop. A unit test that feeds it ten records and asserts one entry in batchItemFailures passes.

That is what makes this different from an ordinary bug. The code is not wrong. It is inert. The half of the contract that would make it work lives in a Terraform module in a different repository, or in a CDK stack a different team owns, or in a checkbox someone clicked in the console eighteen months ago. Nothing in your editor, your linter, or your test suite has any visibility into it.

And an AI assistant, asked to "add partial batch failure handling to this consumer," writes exactly the handler above and reports the job done. It is not hallucinating. It wrote the only half it can see.

Two ends of the same contract, two different findings

When I built the check into Infrawise, it became clear the mismatch has two directions and they are not equally bad.

The first is the mapping-side gap. MissingPartialBatchResponseAnalyzer looks for an sqs, kinesis, or dynamodb trigger with a batch size above 1 and no ReportBatchItemFailures. A batch of one has nothing to partially fail, so it is skipped. This one is graded medium: it is a missing capability, but the handler may genuinely not need it.

The second is the mismatch. BatchResponseMismatchAnalyzer fires when the code builds a batchItemFailures array and the mapping for that trigger has the setting off. That is graded high, and the description says why:

The code reads as correct and its unit tests pass; only the mapping tells the truth.

A missing setting is an absence. A mismatch is an active false belief — someone wrote the handler on purpose, believing per-record reporting was on. Every downstream decision they made about idempotency rests on that belief.

Detecting the code side is cheap. Both scanners just match the name: ts-morph looks for a property or shorthand property called batchItemFailures, and the Python scanner matches the same dict key. There is no control-flow tracing to a return statement, because building an array by that name has no other purpose in a Lambda handler.

The infrastructure side costs nothing either. FunctionResponseTypes rides on the ListEventSourceMappings response that trigger extraction already pages through, so the whole check is a field carried forward plus two analyzers.

The rule that keeps it honest

One detail mattered more than the analyzers themselves. Both checks fire only on an explicit false:

// Only an explicit false is evidence. undefined means the mapping was
// never read, and this finding would be an accusation without evidence.
if (trigger.reportsBatchItemFailures !== false) continue;

If a lambda:ListEventSourceMappings call was denied by IAM, or the page failed halfway, the field is undefined, not false. Treating that as "the setting is missing" would produce a high-severity finding about a mapping nothing was ever read from.

That failure would be worse than staying silent. A tool that occasionally accuses you of a bug you do not have gets muted, and then it is not there on the day it is right. So the extractor raises a partial-extraction error carrying whatever it did page through: the data survives, the source is recorded as partial, and the tools report it as unread rather than reporting a clean bill of health.

What actually changed in the loop

Two things, both small.

Before writing a batch consumer, analyze_function now returns the trigger with batchSize and reportsBatchItemFailures alongside the event shape, and get_lambda_overview carries the same fields for every function. So the assistant knows, before it writes a line, whether the partial-batch response it is about to build will be read or discarded. If it is going to be discarded, the honest answer is either "set FunctionResponseTypes first" or "make this handler idempotent," and now that answer is available at coding time.

And because the mismatch is graded high, infrawise check fails the build on it at the default --fail-on high. The mapping-side gap at medium does not — it is a suggestion, not a broken promise. A handler that reports failures nobody reads is a broken promise.

Key takeaways

A partial batch response has two ends. The handler returns batchItemFailures; the event source mapping must set FunctionResponseTypes: ["ReportBatchItemFailures"]. One without the other is not half a feature, it is zero.
Correct code can be inert. The bugs that survive review are the ones where the file is right and the thing it depends on lives somewhere your tooling never looks.
Grade the mismatch above the gap. A missing setting is an absence. A handler written to use a setting that is off is a false belief the rest of the design rests on.
Never infer a setting is off from a read that failed. undefined and false are different answers. A tool that conflates them will eventually be wrong loudly, and after that nobody reads it.
Until both ends are in place, the handler must be idempotent. That is not a workaround, it is the only thing standing between a poison message and processing the same order ten times.