The provided starting key is invalid

요약 — ExclusiveStartKey가 페이징하는 것의 키 스키마와 일치하지 않습니다. DynamoDB가 LastEvaluatedKey에 반환한 정확한 키 속성 — 전체 기본 키, 그리고 GSI/LSI를 쿼리할 때는 인덱스 키 — 을 같은 이름과 타입으로 포함해야 합니다. LastEvaluatedKey를 그대로 되돌려 전달하세요. 수동으로 조립하는 것이 이것이 깨지는 방식입니다.

무엇을 의미하나요

ValidationException: The provided starting key is invalid

ValidationException: Exclusive Start Key must have same size as table's key schema

ExclusiveStartKey는 Query/Scan에게 어디서 재개할지 알려줍니다. DynamoDB는 이를 테이블의 키 스키마 — 또는 인덱스 쿼리의 경우 LastEvaluatedKey가 지닌 인덱스와 테이블을 합친 키 — 에 대해 검증합니다. 누락된 속성, 여분 속성, 잘못된 이름, 또는 잘못된 타입은 모두 데이터가 읽히기 전에 실패합니다.

왜 발생하나요

파티션 키만으로 키를 수동 구성 — 복합 키 테이블은 시작 키에 파티션 과 정렬 키가 필요합니다.
테이블 키만으로 인덱스 페이징 — GSI/LSI 쿼리의 LastEvaluatedKey는 인덱스 키 속성과 테이블의 기본 키를 모두 포함합니다. 그 모두가 되돌아와야 합니다.
타입 또는 이름 드리프트 — 키가 직렬화되었다가(JSON, URL 파라미터, 캐시) LastEvaluatedKey에 숫자가 있던 곳에 "42"로, 또는 이름이 바뀐 필드로 되돌아왔습니다.
쿼리 간 키 재사용 — 한 테이블/인덱스의 LastEvaluatedKey를 다른 것에 대한 쿼리에, 또는 키 스키마 가정이 바뀐 후 같은 쿼리에 전달.
기본값을 주입하는 래퍼 — 키에 속한다고 생각하는 속성을 채우는 ODM이 시작 키를 스키마 크기를 넘어 채울 수 있습니다.

어떻게 고치나요

LastEvaluatedKey를 손대지 않고 왕복시키세요:

let ExclusiveStartKey;
do {
  const page = await docClient.send(
    new QueryCommand({
      TableName,
      KeyConditionExpression,
      ExpressionAttributeValues,
      ExclusiveStartKey
    })
  );
  items.push(...(page.Items ?? []));
  ExclusiveStartKey = page.LastEvaluatedKey; // verbatim — no rebuild
} while (ExclusiveStartKey);

요청 경계를 넘으면 손실 없이 직렬화하세요 — 페이지네이션 커서가 브라우저로 갔다가 돌아올 때, 항목 필드에서 재구성하는 대신 전체 LastEvaluatedKey 객체를 인코딩하고(예: JSON의 base64), 숫자 타입을 숫자로 유지하세요.
인덱스 페이지네이션에 모든 키 속성을 포함하세요 — 반환된 그대로 인덱스 파티션/정렬 키 와 테이블 파티션/정렬 키.
시작 지점을 조작하지 마세요 — DynamoDB 페이지네이션에는 오프셋이 없습니다. "X 근처에서 시작"이 필요하면 수동으로 만든 ExclusiveStartKey가 아니라 KeyConditionExpression(sk > :x)으로 표현하세요.

LastEvaluatedKey가 테이블이나 인덱스에 대해 실제로 무엇을 담는지 검사하면 추측이 사라집니다 — DynoTable 데스크톱 앱은 쿼리를 페이징하며 원시 커서를 보여주고, DynamoDB Expression Builder는 그것을 중심으로 쿼리 요청을 구성합니다.

References

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

The provided starting key is invalid

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

관련 오류

References