How do I troubleshoot Lambda function SQS ReportBatchItemFailures?

Resolution

Note: You must manually configure Partial Batch Response on your Lambda function to programmatically process partial Amazon SQS batches. For more information, see Reporting batch item failures in the AWS Lambda Developer Guide.

Example AWS Command Line Interface (AWS CLI) command to activate Partial Batch Response for a Lambda function

Important: Replace <esm_UUID> with your Amazon SQS event source mapping's universally unique identifier (UUID). To retrieve your event source mapping's UUID, run the list-event-source-mappings AWS CLI command. If you receive errors when running AWS CLI commands, make sure that you're using the most recent version of the AWS CLI.

aws lambda update-event-source-mapping --uuid <esm_UUID> --function-response-types "ReportBatchItemFailures"

To troubleshoot ReportBatchItemFailures where Lambda retries an entire SQS message batch when there wasn't a function error

Review the Partial Batch Response in your Lambda function's code to see if there are any of the following responses. Then, remediate the issue based on the response that's recorded.

Note: Lambda treats a batch as a complete failure if your function returns any of the following responses.

Responses for an EventResponse that isn't valid JSON

return "Hello world"
return ""

Response for an empty itemIdentifier value

return {"batchItemFailures":[{"itemIdentifier": ""}]}

Response for a null itemIdentifier value

return {"batchItemFailures":[{"itemIdentifier": None}]}

Response for an itemIdentifier value with an incorrect key name

return {"batchItemFailures":[{"bad_key": messageID}]}

Response for an itemIdentifier value with a message ID that doesn't exist

return {"batchItemFailures":[{"itemIdentifier": "random_ID"}]}

Important: Your Lambda function must return a valid itemIdentifier JSON value.

To troubleshoot ReportBatchItemFailures where Lambda doesn't retry any of the partial message batches

Review the Partial Batch Response in your Lambda function's code to see if there are any of the following responses. Then, remediate the issue based on the response that's recorded.

Note: Lambda treats a batch as a complete success when your function returns any of the following responses.

Response for an empty batchItemFailures list

return {"batchItemFailures":[]}

Response for a null batchItemFailures list

return {"batchItemFailures": None}

Responses for an EventResponse with an empty or unexpected JSON value

return {}
return {"Key1":"Value1"}

Responses for a null EventResponse

return
return None

Important: Your Lambda function must return a response that contains a "batchItemFailures" JSON value that includes a list of valid message IDs.

---

Related information

How can I prevent an Amazon SQS message from invoking my Lambda function more than once?