ValidationException: ExpressionAttributeValues contains invalid value

TL;DR — ExpressionAttributeValues 中的某个值为空、类型不受支持，或者你表达式中用到的某个 :placeholder 从未被定义。检查每个 :value 都存在且非空。

含义

常见消息：

ValidationException: ExpressionAttributeValues contains invalid value: One or more parameter values were invalid: An AttributeValue may not contain an empty string for key :s
ValidationException: Value provided in ExpressionAttributeValues unused in expressions: keys: {:x}
ValidationException: An expression attribute value used in expression is not defined; attribute value: :v

为什么会发生

空字符串/空二进制——历史上 DynamoDB 拒绝 ""。空字符串现在_确实_对非键属性是允许的（空 List/Map 也没问题），但键属性中的空值和空 Set 仍然无效。
未定义的占位符——你的表达式引用了 :v，但 ExpressionAttributeValues 没有 :v。
未使用的占位符——你定义了 :x，但没有表达式使用它（DynamoDB 会拒绝整个请求）。
类型错误——传入了一个原始 JS 对象/undefined/NaN，或者（在底层客户端上）用了错误的 {S}/{N} 包裹。
一个空 set 传给了 ADD/DELETE 操作——这些子句接受 set（或对 ADD 而言是数字）操作数，而一个 set 永远不能为空。

如何修复

表达式中的每个 :value 都必须在 ExpressionAttributeValues 中定义，且每个定义的值都必须被使用——让二者精确同步。
防范空值/undefined。 当来源是 undefined 时不要传 :v；改为去掉那个子句。对于 set，确保至少有一个成员。
使用文档客户端（@aws-sdk/lib-dynamodb），让原生 JS 值为你 marshal——它消除了大多数类型包裹错误。

示例

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, UpdateCommand} from '@aws-sdk/lib-dynamodb';

const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));

const email = getEmail(); // could be undefined
const names = {'#e': 'email'};
const values = {':e': email};

if (email == null) throw new Error('email required'); // don't send :e = undefined

await doc.send(
  new UpdateCommand({
    TableName: 'Users',
    Key: {pk: 'USER#1'},
    UpdateExpression: 'SET #e = :e',
    ExpressionAttributeNames: names,
    ExpressionAttributeValues: values
  })
);

DynoTable 中的路径

DynoTable 的更新编辑器会在你键入时绑定值，并在请求离开你的计算机之前拒绝空占位符。使用 ⌘K 打开项目，编辑字段，然后在请求预览中检查生成的 ExpressionAttributeValues 映射 — 不匹配情况会立即显示，而不是在 CloudWatch 中显示为 400。对于无法内联运行的 SDK 代码，请将表达式粘贴到 Expression Builder 中，并将其 :value 映射与你的映射进行比较。使用 ⌘P 切换配置文件以针对引发错误的同一个表进行测试； Settings → Profiles上的测试连接 确认凭据和区域。设置：连接 AWS、安装。空集和未定义的 JS 值是最常见的原因——在调用离开进程之前保护它们。

来源

PutItem — Amazon DynamoDB API Reference（2026-07-13 验证）
Constraints in Amazon DynamoDB（2026-07-13 验证）

参考资料

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