ValidationException: The provided key element does not match the schema

TL;DR — Kunci yang Anda teruskan tidak selaras dengan key schema yang dideklarasikan tabel: nama atribut salah, tipe salah (string vs number), atau sort key yang hilang. Cocokkan kunci permintaan persis dengan KeySchema + AttributeDefinitions.

Apa artinya

# 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

Setiap item DynamoDB dialamatkan oleh primary key-nya — partition key, opsional ditambah sort key — dengan nama dan tipe tetap yang diatur saat pembuatan tabel. GetItem, DeleteItem, UpdateItem dan setiap Key dalam batch harus menyediakan persis kunci itu: sebagaimana dinyatakan referensi API, "for the primary key, you must provide all of the attributes." Kesalahan ini muncul ketika kunci yang disediakan tidak cocok. Ini ValidationException (HTTP 400) dan tidak dapat dicoba ulang — permintaan yang sama gagal sampai kunci diperbaiki.

Mengapa itu terjadi

• Nama atribut salah — Anda meneruskan id tetapi kunci tabel adalah pk.
• Tipe salah — kunci didefinisikan sebagai Number (N) tetapi Anda mengirim String ("123"), atau sebaliknya. "123" dan 123 adalah kunci berbeda bagi DynamoDB.
• Kehilangan sort key — tabel punya kunci komposit tetapi Key Anda hanya punya partition key (atau sort key ekstra pada tabel partition-only).
• Atribut ekstra di Key — map Key harus berisi hanya atribut kunci, tidak lebih.

Bagaimana cara memperbaikinya

1. Periksa key schema tabel (DescribeTable → KeySchema + AttributeDefinitions), lalu buat Key permintaan cocok nama-per-nama dan tipe-per-tipe. Panel statistik tabel DynoTable menampilkan key schema yang sama — partition key, sort key, dan tipenya — dalam sekali pandang.
2. Perbaiki ketidakcocokan number/string. Jika kunci adalah N, teruskan number JS (Document Client me-marshalnya); dengan klien low-level gunakan {N: '123'}, bukan {S: '123'}.
3. Sediakan kunci komposit penuh. Tabel kunci komposit butuh partition dan sort key pada setiap panggilan berbasis item.

Contoh

// 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'}}));

FAQ

Apa yang menyebabkan "The provided key element does not match the schema"? Kunci dalam permintaan Anda tidak selaras dengan key schema yang dideklarasikan tabel: nama atribut salah, tipe salah (kunci Number dikirim sebagai String atau sebaliknya), sort key yang hilang pada tabel kunci komposit, atau atribut non-kunci ekstra dalam map Key.

Bagaimana cara memeriksa key schema tabel saya? Panggil DescribeTable dan baca KeySchema ditambah AttributeDefinitions, lalu buat Key permintaan cocok nama-per-nama dan tipe-per-tipe. Tabel kunci komposit butuh partition key dan sort key pada setiap panggilan berbasis item.

Kesalahan terkait

• Kondisi kueri elemen skema kunci tidak ada
• ValidationException (ikhtisar)
• Pelajari: DynamoDB data types · Composite primary keys

Referensi

• GetItem — Amazon DynamoDB API Reference
• Core components of Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Constraints in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.