ValidationException: Invalid UpdateExpression

TL;DR — 你的 UpdateExpression 格式錯誤。十有八九是一個保留字（如 status、name、size）被直接使用了——把它換成 ExpressionAttributeNames 中的一個 #placeholder。訊息會指明確切的標記。

這是什麼意思

典型訊息：

ValidationException: Invalid UpdateExpression: Attribute name is a reserved keyword; reserved keyword: status
ValidationException: Invalid UpdateExpression: Syntax error; token: "=", near: "SET status ="
ValidationException: Invalid UpdateExpression: An expression attribute value used in expression is not defined; attribute value: :s

DynamoDB 解析運算式字串，並拒絕任何不是有效語法或引用了未定義預留位置的東西。

為什麼會發生

直接使用了保留字。 DynamoDB 有數百個保留字——@@P0@@、@@P1@@、@@P2@@、@@P3@@、@@P4@@、@@P5@@。在運算式中直接使用它們會導致語法錯誤。保留字檢查器會對照完整列表測試你的屬性名，並輸出別名對映。
缺少你引用的 #name 的 ExpressionAttributeNames 條目。
缺少你引用的 :value 的 ExpressionAttributeValues 條目。
動詞語法錯誤——錯誤地混用子句（SET、REMOVE、ADD、DELETE 各有其自己的語法），或一個多餘的 =。
含特殊字元的屬性名（點、橫線）在沒有預留位置的情況下被使用。

如何修正

透過 ExpressionAttributeNames 為每個屬性名起別名（#status）——它完全繞開了保留字列表，因此給所有名稱都起別名是一個安全的習慣。
在 ExpressionAttributeValues 中定義你引用的每個 :value。
使用正確的子句。 SET 用於寫入/覆蓋，REMOVE 用於刪除一個屬性，ADD 用於原子的數字/集合自增，DELETE 用於從集合中移除。

範例

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

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

await doc.send(
  new UpdateCommand({
    TableName: 'Orders',
    Key: {pk: 'ORDER#1'},
    // #status aliases the reserved word "status"
    UpdateExpression: 'SET #status = :s, updatedAt = :t',
    ExpressionAttributeNames: {'#status': 'status'},
    ExpressionAttributeValues: {':s': 'SHIPPED', ':t': Date.now()}
  })
);

先在 DynoTable 中檢查

當你的應用程式更新失敗時，請在更改生產程式碼之前在 DynoTable 中重現它。使用 ⌘K 開啟表，選擇該項目，然後使用內聯更新編輯器 — DynoTable 自動為保留屬性名稱新增別名，並顯示生成的 UpdateExpression 和兩個屬性對映。暫存 (⌘S) 允許你在提交之前預覽編輯並捕獲語法錯誤。對於批次修復，請將失敗的運算式貼上到 Expression Builder 中，並將其輸出與 SDK 傳送的內容進行比較。 Profile 切換 (⌘P) 使測試在與錯誤相同的帳戶上執行；使用“設定”→“設定檔案”上的“測試連線”來確認設定檔案匹配。有關設定檔案設定，請參閱連線 AWS和安裝。當錯誤命名特定標記（例如 status 或 data）時，交叉檢查 reserved words checker 中的屬性名稱。對每個屬性名稱（而不僅僅是保留的屬性名稱）使用別名是一種安全的習慣，可以完全防止此類錯誤。

來源

Using update expressions in DynamoDB（2026-07-13 驗證）
Reserved words in DynamoDB（2026-07-13 驗證）

參考資料

最後核實於 2026-07-13，依據上方連結的 AWS 官方文件。