Size of hashkey has exceeded the maximum size limit of 2048 bytes

TL;DR — DynamoDB 限制键长度：一个分区（hash）键值最多 2048 字节，一个排序（range）键值最多 1024 字节，以 UTF-8（或原始二进制）字节测量。键超过限制的写入会被拒绝。缩短键——对长的值做哈希，或把庞大的数据移入一个非键属性。

含义

ValidationException: One or more parameter values were invalid: Size of hashkey has exceeded the maximum size limit of2048 bytes

# sort-key variant:
ValidationException: One or more parameter values were invalid: Aggregated size of all range keys has exceeded the size limit of 1024 bytes

# on DynamoDB Local you get one combined sentence instead, naming neither key:
ValidationException: Hash primary key values must be under 2048 bytes, and range primary key values must be under 1024 bytes

（是的，"of2048" 中缺少的空格就在服务实际的消息里。）键属性由 DynamoDB 建立索引并进行物理分区，因此它们的长度被限制在远低于 400 KB 的项目限制之下。分区键值必须是 1 到 2048 字节，排序键值必须是 1 到 1024 字节。字节数是编码后的大小（字符串用 UTF-8，二进制用原始字节）——多字节字符不止算一个。它是一个 HTTP 400 ValidationException，属于客户端错误，在键变小之前不可重试。

为什么会发生

一个长字符串作为分区键——一个 URL、完整文档、编码的二进制块，或直接用作键值的连接复合键。
一个冗长的复合排序键——用 # 连接的许多段合计超过 1024 字节。
键中的 Base64 / 序列化数据——编码把字节数膨胀过了限制。
多字节文本——其 UTF-8 编码比字符数所暗示的更大的非 ASCII 内容。

如何修复

对长的值做哈希——存储一个确定性摘要（例如 SHA-256，约 32 字节）作为键，把完整的值保留在一个单独的非键属性中。
选择一个更紧凑的键——用一个更短的自然标识符代替庞大的字段。
缩短复合键——裁剪或缩写构成 # 连接排序键的那些段。
把超大的内容移出键进入一个常规属性（它只需容纳 400 KB 的项目限制）。

从 DynoTable 连接

将草稿键值粘贴到 item size calculator 中，并在写入之前检查字节数是否符合 2048/1024 限制。在 DynoTable 中，暂存 (⌘S) 捕获使用 ⌘K 打开的测试项目上的过大按键。当缩短组合键时，原型查询在Query Builder中。使用 ⌘P 切换配置文件； 在“设置”→“配置文件”上测试连接。参见连接 AWS和安装。

来源

Constraints in Amazon DynamoDB（2026-07-13 验证）
Supported data types and naming rules（2026-07-13 验证）

参考资料

最后核实于 2026-07-13，依据上方链接的 AWS 官方文档。