An operand in the update expression has an incorrect data type

TL;DR — 更新的操作会针对实际存储的内容（以及你发送的值）做类型检查，而其中之一不匹配：对一个不是数字或集合的属性做 ADD、对一个不是列表的东西做 list_append，或者一个元素类型与存储集合不匹配的集合操作数。让操作数与存储的类型匹配——或者修复那个类型漂移了的项目。

含义

ValidationException: An operand in the update expression has an incorrect data type

更新操作有严格的类型规则：ADD 只对数字和集合（SS/NS/BS）有效，DELETE 只对集合有效，而 list_append 接受两个列表。DynamoDB 在写入时针对项目当前的属性类型对表达式求值——因此同一个请求在一个项目上可能成功，而在另一个其属性持有不同类型的项目上失败。一个近亲会更早地在表达式解析时被拒绝，当_发送值的_类型永远无法适配运算符时：

ValidationException: Invalid UpdateExpression: Incorrect operand type for
operator or function; operator: ADD, operand type: LIST

为什么会发生

• ADD counter :one，但 counter 存储为字符串——例如项目导入时用了 "5"（类型 S）而不是 5（类型 N）。
• ADD tags :t 配一个列表（L）操作数——ADD 收集进_集合_，而非列表。列表用 SET + list_append 追加。
• list_append(mylist, :v)，而 mylist 是一个 map、集合或标量——两个参数都必须是列表（把单个元素包成一个单元素列表）。
• 集合元素类型不匹配——ADD/DELETE 用一个字符串集合（SS）操作数针对一个存储的数字集合（NS），或反之。
• 跨项目的类型漂移——混合的写入者（一次旧的导入、另一个服务）在某些项目上把同一个属性留作 N、在另一些上留作 S，因此更新只是有时失败。

如何修复

1. 计数器： 把值存储为数字并发送一个数字操作数：

   UpdateExpression: 'ADD #c :one',
   ExpressionAttributeValues: {':one': 1}   // {N: "1"} — not a string

2. 列表： 用 SET 配 list_append，并把新元素包进一个列表：

   UpdateExpression: 'SET #l = list_append(if_not_exists(#l, :empty), :new)',
   ExpressionAttributeValues: {':new': ['item'], ':empty': []}

3. 集合： 让 ADD/DELETE 操作数保持与存储属性相同的集合类型（SS 配 SS，NS 配 NS）。

4. 修复漂移的项目——找到属性携带错误类型的那些项目并一次性重写它们；"同一个更新在某些项目上失败"这一症状总是数据问题，而非代码问题。

类型漂移在大多数控制台中是不可见的——DynoTable 桌面应用在每个属性的值旁边显示它实际存储的类型，因此一个作为字符串的 "5" 计数器会立即显现。

相关错误

• Float types are not supported——来自 SDK 侧的数字类型摩擦。
• Number overflow
• Type mismatch: key element does not match schema
• 学习：Update expressions · Atomic counters · Data types

References

• Using update expressions in DynamoDB — Amazon DynamoDB Developer Guide
• TransactWriteItems — Amazon DynamoDB API Reference
• Supported data types and naming rules in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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