ValidationException: The provided key element does not match the schema

TL;DR — 渡したキーが、テーブルの宣言されたキースキーマと揃っていません: 誤った属性名、誤った型（文字列 vs 数値）、または欠落したソートキーです。リクエストのキーを KeySchema + AttributeDefinitions に正確に一致させてください。

意味

# what the engine actually returns, reproduced against DynamoDB Local — GetItem with pk passed as N where the schema declares S:
ValidationException: One or more parameter values were invalid: Type mismatch for key

すべての DynamoDB アイテムは、その プライマリキー — パーティションキー、オプションでソートキー — によって指定され、名前と型はテーブル作成時に固定されます。GetItem、DeleteItem、UpdateItem、バッチ内の各 Key は、まさにそのキーを渡す必要があります。API リファレンスが述べるように、「プライマリキーには、すべての属性を渡す必要があります」。このエラーは、渡されたキーが一致しないときに発生します。これは ValidationException（HTTP 400）でリトライ不可です。キーが修正されるまで同じリクエストは失敗します。

発生する理由

誤った属性名 — id を渡したが、テーブルのキーは pk である。
誤った型 — キーは数値（N）として定義されているが、文字列（"123"）を送った、またはその逆。DynamoDB にとって "123" と 123 は異なるキーです。
ソートキーの欠落 — テーブルは複合キーを持つが、Key にはパーティションキーしかない（またはパーティションのみのテーブルに余分なソートキー）。
Key 内の余分な属性 — Key マップにはキー属性だけを含める必要があり、それ以外は含めません。

修正方法

テーブルのキースキーマを確認します（DescribeTable → KeySchema + AttributeDefinitions）。それからリクエストの Key を名前ごと、型ごとに一致させます。DynoTable のテーブル統計パネルは同じキースキーマ — パーティションキー、ソートキー、それらの型 — を一目で表示します。
数値/文字列の不一致を修正します。 キーが N なら JS の数値を渡します（Document Client がマーシャルします）。低レベルクライアントでは {S: '123'} ではなく {N: '123'} を使います。
完全な複合キーを渡します。 複合キーのテーブルは、すべてのアイテムベースの呼び出しでパーティションとソートの両方のキーを必要とします。

例

// Table: Users, key = { pk (S) HASH, sk (S) RANGE }
import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, GetCommand} from '@aws-sdk/lib-dynamodb';

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

//  both key parts, correct names/types
await doc.send(new GetCommand({TableName: 'Users', Key: {pk: 'USER#1', sk: 'PROFILE'}}));

//  missing sort key → "provided key element does not match the schema"
// await doc.send(new GetCommand({TableName: 'Users', Key: {pk: 'USER#1'}}));

よくある質問

"The provided key element does not match the schema" は何が原因ですか？ リクエスト内のキーが、テーブルの宣言されたキースキーマと揃っていません: 誤った属性名、誤った型（数値キーが文字列として送られた、またはその逆）、複合キーのテーブルでの欠落したソートキー、または Key マップ内の余分な非キー属性です。

テーブルのキースキーマを確認するには？ DescribeTable を呼び出して KeySchema と AttributeDefinitions を読み、リクエストの Key を名前ごと、型ごとに一致させます。複合キーのテーブルは、すべてのアイテムベースの呼び出しでパーティションキーとソートキーの両方を必要とします。

参考資料

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