ValidationException: The provided key element does not match the schema

요약 — 전달한 키가 테이블의 선언된 키 스키마와 맞지 않습니다: 잘못된 속성 이름, 잘못된 타입(문자열 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")을 보냈거나 그 반대. "123"과 123은 DynamoDB에 다른 키입니다.
정렬 키 누락 — 테이블에 복합 키가 있는데 Key에 파티션 키만 있습니다(또는 파티션 전용 테이블에 여분의 정렬 키).
Key의 여분 속성 — Key map은 오직 키 속성만 포함해야 하며 다른 것은 안 됩니다.

어떻게 해결하는가

테이블의 키 스키마를 확인하세요(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'}}));

FAQ

"The provided key element does not match the schema"는 무엇 때문에 발생하나요? 요청의 키가 테이블의 선언된 키 스키마와 맞지 않습니다: 잘못된 속성 이름, 잘못된 타입(숫자 키를 문자열로 보내거나 그 반대), 복합 키 테이블에서 누락된 정렬 키, 또는 Key map의 여분 키가 아닌 속성입니다.

테이블의 키 스키마를 어떻게 확인하나요? DescribeTable을 호출하고 KeySchema와 AttributeDefinitions를 읽은 다음, 요청의 Key를 이름 대 이름, 타입 대 타입으로 일치시키세요. 복합 키 테이블은 모든 항목 기반 호출에 파티션 키와 정렬 키가 모두 필요합니다.

참고 자료

공식 AWS 문서(위 링크)를 기준으로 2026-07-13에 마지막으로 검증되었습니다.