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 復現——上方輸出為原樣照錄。