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 官方文件。