Value provided in ExpressionAttributeNames unused in expressions

TL;DR — 你在 ExpressionAttributeNames 中声明了一个名称占位符（例如 #status），但没有任何表达式引用它。DynamoDB 要求每一个声明的别名都必须在 KeyConditionExpression、FilterExpression、UpdateExpression、ConditionExpression 或 ProjectionExpression 中被使用。删掉这个没用上的别名——或者修好那个本该引用它的表达式。

含义

ValidationException: 1 validation error detected: Value provided in ExpressionAttributeNames unused in
expressions: keys: {#status}

# what the engine actually returns, reproduced against DynamoDB Local:
ValidationException: 1 validation error detected: Value provided in ExpressionAttributeNames unused in expressions: keys: {#status}

ExpressionAttributeNames 是属性名别名的替换映射（保留字或含特殊字符的名称需要它）。DynamoDB 强制执行一份严格的双向约定：你在表达式中用到的每个别名都必须声明，并且你声明的每个别名都必须被用到。一条遗留的、未被引用的条目就会触发这个 HTTP 400 ValidationException。它发生在客户端，在映射与表达式对上号之前不可重试。

为什么会发生

编辑表达式后残留的旧别名——你把 #status = :s 从表达式里删掉了，却忘了从名称映射中删除 #status。
生成的映射声明过头——某个映射层为每个属性都发出了别名，包括最终表达式根本没碰的那些。
别名放错了映射——你想要的是 :status（一个值），却声明成了 #status（一个名称）。
拼写不一致——表达式用的是 #stat，而映射声明的是 #status，于是 #status 从技术上讲就没被使用。

如何修复

删除消息中点名的那个未使用别名，把它从 ExpressionAttributeNames 中移除。
让映射与表达式保持同步——只有当表达式确实引用某个 #name 时才声明它。
检查名称与值是否混淆——# 别名放在 ExpressionAttributeNames 里，: 占位符放在 ExpressionAttributeValues 里。
重新生成请求，让名称、值和表达式文本一起构建，而不是手工拼装。

在 DynoTable 中检查

DynoTable 是更新和过滤编辑器中保留属性名称的别名 - 输出中的每个 #placeholder 都在表达式中引用。用⌘K打开一个表格，编辑一个项目，然后复制生成的ExpressionAttributeNames地图。交叉检查 reserved words checker 中失败的 SDK 请求 — 它会打印需要 # 前缀的名称的别名映射。使用 ⌘P 切换配置文件；参见连接 AWS和安装。

来源

Expression attribute names (aliases) in DynamoDB（2026-07-13 验证）
Reserved words in DynamoDB（2026-07-13 验证）

复现方法

没有表达式引用的 ExpressionAttributeNames 条目：

await client.send(
  new UpdateItemCommand({
    TableName: 'orders',
    Key: {pk: {S: 'ORDER#1'}, sk: {S: 'META'}},
    UpdateExpression: 'SET stat = :v', // note: 'stat', not '#unused'
    ExpressionAttributeNames: {'#unused': 'status'},
    ExpressionAttributeValues: {':v': {S: 'shipped'}}
  })
);

实际输出：

ValidationException: 1 validation error detected: Value provided in ExpressionAttributeNames unused in expressions: keys: {#unused}
HTTP 400

该消息命名了有问题的密钥，这使得它成为少数几个无需阅读其他内容即可处理的 DynamoDB 验证错误之一。它通常出现在编辑从表达式中删除占位符但保留其声明之后。

参考资料

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

2026-07-26 针对 DynamoDB Local 2.x 与 AWS SDK for JavaScript v3.1095.0 复现——上方输出为原样照录。