ValidationException: Item size has exceeded the maximum allowed size
TL;DR — A DynamoDB item can be at most 400 KB (attribute names + values combined). Your write pushes an item over that. Move the large field out (to S3, or split across items) and store a reference instead.
What it means
ValidationException: Item size has exceeded the maximum allowed size of 409600 bytes409,600 bytes = 400 KB. The limit counts the entire item: every attribute name plus its value, UTF-8 encoded, including nested map/list overhead. An UpdateItem that grows an existing item past 400 KB fails the same way.
Why it happens
- Storing large blobs inline — base64 images, PDFs, big JSON documents.
- An unbounded list/map (append-only arrays, event logs) that grows over time until it crosses 400 KB.
- Long attribute names multiplied across a big item.
- Denormalizing too much into a single item.
How to fix it
- Offload large values to S3. Store the object in S3 and keep only the key/URL in DynamoDB. This is the standard pattern for anything approaching the limit.
- Split the data across multiple items. Use the item-collection / vertical-partition pattern — one logical entity as several items sharing a partition key.
- Cap growing collections. Don't let a single item accumulate an unbounded list; roll entries into child items keyed by sort key.
- Compress genuinely large text before storing (gzip → binary attribute), if S3 isn't an option.
Example — reference pattern
// Instead of storing the blob inline, store an S3 pointer:
await doc.send(
new PutCommand({
TableName: 'Documents',
Item: {
pk: 'DOC#1',
title: 'Q3 report',
s3Key: 'documents/DOC#1/report.pdf', // the bytes live in S3
sizeBytes: 2_400_000
}
})
);Related errors
- ItemCollectionSizeLimitExceededException — the 10 GB collection limit (LSI tables).
- ValidationException (overview)
- Learn: Item size & the 400 KB limit · Item collections