Error: DynamoDB BatchWriteItem error

BatchWriteItem can reject an invalid request or return a successful response with writes still in UnprocessedItems. Check both the exception and the response body. A batch supports puts and deletes, not updates or per-item conditions.

Fix request validation first

• Send at most 25 operations across all tables in one request. The request can contain up to 16 MB of transmitted data; each stored item must fit 400 KB. These are separate limits.
• Include the complete primary key with matching attribute types. A DeleteRequest contains only the table key, including the sort key when the table has one.
• Remove duplicate operations on the same full primary key within a batch, including a put and delete of the same item.
• Confirm the table exists in the client’s account, Region, and endpoint. A backup does not block writes, and an UPDATING table does not universally reject them. Deleting an absent item is allowed.

Handle partially processed batches

This SDK v3 example uses ordinary JavaScript values with DynamoDBDocumentClient. It resubmits only unprocessed writes, uses jitter, and stops after a bounded number of application retries. The numeric retry settings below are example application policy, not DynamoDB limits.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, BatchWriteCommand } from "@aws-sdk/lib-dynamodb";
import { setTimeout as sleep } from "node:timers/promises";

const db = DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-1" }));
let pending = { Orders: [
  { PutRequest: { Item: { pk: "ORDER#123", sk: "DETAIL", status: "NEW" } } },
  { DeleteRequest: { Key: { pk: "ORDER#456", sk: "DETAIL" } } }
] };
for (let attempt = 0; attempt < 6 && Object.keys(pending).length; attempt++) {
  const result = await db.send(new BatchWriteCommand({ RequestItems: pending }));
  pending = result.UnprocessedItems ?? {};
  if (Object.keys(pending).length) {
    await sleep(Math.random() * Math.min(2000, 100 * 2 ** attempt));
  }
}
if (Object.keys(pending).length) {
  throw new Error("Batch incomplete; retain pending writes for recovery");
}

SDK retries handle retryable request exceptions; they do not drain a successful response’s UnprocessedItems for you. If the request itself throws after SDK retries, propagate the error and retain the work for recovery. Avoid replaying already completed puts if another writer may have changed those items.

For persistent throttling, inspect the affected table or GSI and spread writes across keys. Batch writes are not atomic as a group. Use individual conditional writes or a transaction when correctness depends on conditions or all-or-nothing behavior.

See batch write patterns and AWS documentation.