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 は "" を拒否していました。空文字列は今では非キー属性で 許可されており（空のリスト/マップも問題ありません）、しかし キー 属性の空の値と空の セット は依然として無効です。
• 未定義のプレースホルダー — 式が :v を参照するのに ExpressionAttributeValues に :v がない。
• 未使用のプレースホルダー — :x を定義したがどの式も使っていない（DynamoDB はリクエスト全体を拒否）。
• 誤った型 — 素の JS オブジェクト/undefined/NaN を渡す、または（低レベルクライアントで）誤った {S}/{N} ラッパー。
• ADD/DELETE 操作に渡された空のセット — それらの句はセット（ADD では数値）オペランドを取り、セットは決して空にできません。

修正方法

1. 式内の すべての :value は ExpressionAttributeValues で定義される必要があり、定義したすべての値は使用される必要があります — 両者を正確に同期させます。
2. 空/undefined を防ぎます。 ソースが undefined のとき :v を渡さず、代わりに句を落とします。セットには少なくとも1つのメンバーを確保します。
3. Document Client（@aws-sdk/lib-dynamodb）を使い、ネイティブの JS 値をマーシャルさせます。ほとんどの型ラッパーのミスを取り除きます。

例

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 コードなら、式を式ビルダーに貼り付け、出力される :value のマップを自分のものと突き合わせましょう。エラーを出したのと同じテーブルで試すには ⌘P でプロファイルを切り替えます。Settings → Profiles の Test Connection が認証情報とリージョンを確認してくれます。セットアップ: AWS に接続する、インストール。原因として最も多いのは空のセットと JS の undefined です — 呼び出しがプロセスを離れる前に、どちらも防いでください。

出典

• PutItem — Amazon DynamoDB API Reference (2026-07-13 時点で検証)
• Constraints in Amazon DynamoDB (2026-07-13 時点で検証)

関連するエラー

• UpdateExpression の構文が不正
• ValidationException (overview)
• 学習: 式属性名と値

参考資料

• PutItem — Amazon DynamoDB API Reference
• Constraints in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Using update expressions in DynamoDB — Amazon DynamoDB Developer Guide

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。