ValidationException: The provided key element does not match the schema

TL;DR — İlettiğiniz anahtar, tablonun bildirilen anahtar şemasıyla hizalanmıyor: yanlış öznitelik adı, yanlış tür (string ile sayı) ya da eksik bir sıralama anahtarı. İsteğin anahtarını KeySchema + AttributeDefinitions ile tam olarak eşleştirin.

Ne anlama gelir

# 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

Her DynamoDB öğesi, birincil anahtarıyla adreslenir — bir bölüm anahtarı, isteğe bağlı olarak artı bir sıralama anahtarı — tablo oluşturmada ayarlanmış sabit adlar ve türlerle. GetItem, DeleteItem, UpdateItem ve bir toplu istekteki her Key tam olarak o anahtarı sağlamalıdır: API referansının dediği gibi, "birincil anahtar için, tüm öznitelikleri sağlamalısınız." Bu hata, sağlanan anahtar eşleşmediğinde tetiklenir. Bir ValidationException'dır (HTTP 400) ve yeniden denenebilir değildir — anahtar düzeltilene kadar aynı istek başarısız olur.

Neden olur

Yanlış öznitelik adı — id ilettiniz ama tablonun anahtarı pk.
Yanlış tür — anahtar Number (N) olarak tanımlanmış ama siz bir String ("123") gönderdiniz ya da tam tersi. "123" ve 123, DynamoDB için farklı anahtarlardır.
Sıralama anahtarının eksik olması — tablonun bileşik bir anahtarı var ama Key'inizde yalnızca bölüm anahtarı var (ya da yalnızca-bölüm bir tabloda fazladan bir sıralama anahtarı).
Key'de fazladan öznitelikler — Key map'i yalnızca anahtar özniteliklerini içermelidir, başka hiçbir şey değil.

Nasıl düzeltilir

Tablonun anahtar şemasını kontrol edin (DescribeTable → KeySchema + AttributeDefinitions), sonra isteğin Key'ini ad-ad ve tür-tür eşleştirin. DynoTable'ın tablo istatistikleri paneli aynı anahtar şemasını — bölüm anahtarı, sıralama anahtarı ve türleri — bir bakışta gösterir.
Sayı/string uyuşmazlıklarını düzeltin. Anahtar N ise, bir JS sayısı iletin (Document Client onu marshal eder); düşük seviyeli istemciyle {S: '123'} değil, {N: '123'} kullanın.
Tam bileşik anahtarı sağlayın. Bileşik anahtarlı tablolar her öğe tabanlı çağrıda hem bölüm hem de sıralama anahtarına ihtiyaç duyar.

Örnek

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

SSS

"The provided key element does not match the schema"a ne neden olur? İsteğinizdeki anahtar, tablonun bildirilen anahtar şemasıyla hizalanmıyor: yanlış bir öznitelik adı, yanlış bir tür (String olarak gönderilen bir Number anahtarı ya da tam tersi), bileşik anahtarlı bir tabloda eksik bir sıralama anahtarı ya da Key map'inde fazladan anahtar olmayan öznitelikler.

Tablomun anahtar şemasını nasıl kontrol ederim? DescribeTable çağırın ve KeySchema artı AttributeDefinitions'ı okuyun, sonra isteğin Key'ini ad-ad ve tür-tür eşleştirin. Bileşik anahtarlı tablolar her öğe tabanlı çağrıda hem bölüm anahtarına hem de sıralama anahtarına ihtiyaç duyar.

İlgili hatalar

Kaynaklar

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.