자주 발생하는 DynamoDB 오류 (및 해결 방법)
개발자가 가장 자주 마주치는 DynamoDB 오류 — 각 오류의 의미, 원인, 정확한 해결 방법을 함께 설명합니다.
검증 및 표현식 오류 (52)
DynamoDB ValidationException — 원인 및 해결 방법
DynamoDB ValidationException은 요청이 실행되기 전에 형식 오류로 거부되었다는 뜻입니다. 흔한 트리거, 읽어야 할 메시지, 그리고 각각의 해결 방법을 설명합니다.
"Query condition missed key schema element" — DynamoDB 해결
Query condition missed key schema element는 KeyConditionExpression에 파티션 키 등호 조건이 빠졌다는 뜻입니다. 대신 GSI를 쿼리하거나 Scan을 쓰세요.
"The provided key element does not match the schema" — DynamoDB 해결
이 ValidationException은 키 속성의 이름이나 타입이 테이블의 KeySchema와 맞지 않는다는 뜻입니다 — 누락된 정렬 키, 또는 문자열로 보낸 숫자.
"잘못된 UpdateExpression" 구문 오류 — DynamoDB 수정
잘못된 UpdateExpression은 일반적으로 원시로 사용되는 예약된 키워드이거나 누락된 #name 또는 :value 자리 표시자입니다. ExpressionAttributeNames로 예약된 이름에 별칭을 지정하고 ExpressionAttributeValues로 값을 바인딩합니다.
"ExpressionAttributeValues에 잘못된 값이 포함되어 있습니다." — DynamoDB 수정
이 ValidationException은 ExpressionAttributeValues의 값이 비어 있거나, 잘못된 유형이거나, 표현식이 정의되지 않은 자리 표시자를 의미합니다.
"Item size has exceeded the maximum allowed size" — DynamoDB 해결
DynamoDB 항목은 400 KB로 제한됩니다. 이 ValidationException은 항목이 한도를 넘었다는 뜻입니다 — 크기를 확인하고 다시 한도 아래로 내리는 방법을 설명합니다.
DynamoDB ConditionalCheckFailedException — 원인 및 해결
ConditionalCheckFailedException은 ConditionExpression이 false로 평가되어 DynamoDB가 쓰기를 거부하고 항목을 그대로 두었다는 뜻입니다.
DynamoDB TransactionCanceledException — 취소 사유 해독하기
TransactionCanceledException은 한 항목이 실패해 트랜잭션 전체가 롤백되었다는 뜻입니다. CancellationReasons 배열을 읽어 어떤 항목이 왜 실패했는지 찾으세요.
DynamoDB SerializationException — 원인 및 해결
SerializationException은 보낸 JSON이 DynamoDB의 와이어 형식과 맞지 않는다는 뜻입니다 — 보통 숫자를 문자열로 감싼 경우입니다. 타입 지정 AttributeValue 래퍼를 고치세요.
"Supplied AttributeValue is empty" — DynamoDB 해결
이 ValidationException은 AttributeValue에 타입이 지정된 값이 전혀 없다는 뜻입니다 — 빈 set, 빈 키 문자열, 또는 정의되지 않은 필드. 제거하거나 값을 주세요.
"One or more parameter values were invalid" — DynamoDB 해결
이 ValidationException은 어떤 값이 DynamoDB 규칙을 위반한다는 뜻입니다 — 빈 set, 빈 키 문자열, 또는 타입 불일치. 메시지가 해당 파라미터를 알려 줍니다.
"Invalid size for parameter" — DynamoDB 벡터 쓰기 해결
임베딩의 차원 수가 벡터 인덱스와 일치하지 않으면 DynamoDB가 벡터 쓰기를 거부합니다. 메시지가 해당 속성과 두 크기를 모두 알려 줍니다.
"Search vector contains invalid values" — DynamoDB 해결
SearchVectors는 DynamoDB의 L 타입으로 감싸졌거나 부동소수점이 아닌 값을 담은 쿼리 벡터를 거부합니다. 이 파라미터는 List 속성이 아니라 순수 JSON 배열입니다.
"SearchConditionExpression must be provided" — DynamoDB 해결
HASH 검색 스키마 키가 있는 벡터 인덱스는 모든 SearchVectors 호출이 정확히 하나의 파티션 값을 고정하도록 요구합니다. 이 필터는 인덱스 생성 시점부터 선택 사항이 아니게 되었습니다.
"Query key condition not supported" — DynamoDB 해결
DynamoDB는 키 스키마가 허용하지 않는 연산자를 쓴 KeyConditionExpression을 거부합니다 — 파티션 키는 등호만 받습니다. 허용되는 연산자를 정리했습니다.
"Attribute name is a reserved keyword" — DynamoDB 해결
DynamoDB는 status, name, size 같은 예약어를 그대로의 속성 이름으로 쓰면 거부합니다. #status 같은 ExpressionAttributeNames 플레이스홀더로 별칭하세요.
"Float types are not supported" — DynamoDB boto3 해결
DynamoDB가 정확한 십진수를 저장하기 때문에 boto3는 TypeError "Float types are not supported"를 발생시킵니다. float는 문자열 형태를 거쳐 decimal.Decimal로 변환하세요.
"Number overflow" — DynamoDB 숫자 크기 한도 해결
DynamoDB의 N 타입은 38자리 정밀도와 최대 약 9.9E+125의 크기를 담습니다. 그 너머의 큰 ID와 고정밀도 값은 문자열로 저장하세요.
"The provided expression refers to an attribute that does not exist" — 해결
UpdateExpression이나 ConditionExpression이 항목에 없는 경로를 참조합니다 — 누락된 부모 map, 오타, 또는 누락된 속성에 대한 연산.
"제공된 항목 키 목록에 중복 항목이 포함되어 있습니다"(BatchGetItem) — 수정
DynamoDB는 테이블의 키 목록이 기본 키를 반복하는 경우 BatchGetItem을 거부합니다. 전체 배치가 실패하므로 전송하기 전에 키 중복을 제거하세요.
"Provided list of item keys contains duplicates" (BatchWriteItem) — 해결
DynamoDB는 두 작업이 같은 기본 키를 대상으로 하면 BatchWriteItem을 거부합니다. 하나의 배치는 같은 항목을 두 번 건드릴 수 없으니 중복을 합치세요.
"표현식 크기가 최대 허용 크기를 초과했습니다."(4KB) — 수정
DynamoDB는 모든 표현식 문자열을 4KB로 제한합니다. 거부된 FilterExpression, ConditionExpression 또는 UpdateExpression 과거입니다. 축소하는 방법.
"모든 범위 키의 집계된 크기가 크기 제한을 초과했습니다." — 수정
DynamoDB는 정렬 키를 1024바이트로, 파티션 키를 2048바이트로 제한합니다. 키 속성 값을 축소하거나 긴 식별자를 해시한 후 저장하세요.
"필터 표현식에는 기본 키가 아닌 속성만 포함될 수 있습니다." — 수정
DynamoDB는 파티션 또는 정렬 키의 이름을 지정하는 FilterExpression을 거부합니다. 키는 KeyConditionExpression에 속합니다. 쿼리를 재구성하는 방법은 다음과 같습니다.
DynamoDB BatchGetItem 100개 항목 제한 - "Too Many Items" 수정
BatchGetItem은 호출당 최대 100개 항목(및 16MB)을 허용합니다. 더 많은 것을 요청하면 DynamoDB가 전체 요청을 거부합니다. 한계와 청킹 루프.
"BatchWriteItem 호출에 요청된 항목이 너무 많습니다" — 수정
BatchWriteItem은 호출당 최대 25개의 넣기 또는 삭제 작업을 허용합니다. 더 많이 보내면 DynamoDB가 ValidationException을 통해 전체 요청을 거부합니다.
DynamoDB "Can Not Use Both Expression and Non-Expression Parameters" — 수정
DynamoDB는 KeyConditions와 같은 레거시 파라미터를 KeyConditionExpression과 혼합하는 요청을 거부합니다. 레거시 매개변수를 삭제하고 표현식을 사용하십시오.
"Local secondary indexes must be specified at table creation" — 수정
로컬 보조 인덱스는 테이블이 생성될 때만 정의할 수 있으며 나중에 추가할 수 없습니다. 제약 조건이 존재하는 이유와 이를 해결하는 방법
DynamoDB TransactionCanceledException — ConditionalCheckFailed 해결
TransactWriteItems가 ConditionalCheckFailed로 취소되었다면 한 항목의 조건이 실패해 트랜잭션 전체가 롤백된 것입니다. 그 항목을 찾는 방법을 설명합니다.
"표현식에서 사용되지 않는 ExpressionAttributeNames에 제공된 값" — 수정
DynamoDB는 표현식 참조가 없는 ExpressionAttributeNames 별칭을 선언하는 요청을 거부합니다. 제거하거나 놓친 표현을 수정하세요.
"표현식에서 사용되지 않는 ExpressionAttributeValues에 제공된 값" — 수정
DynamoDB는 표현식이 사용하지 않는 ExpressionAttributeValues 자리 표시자를 선언하는 요청을 거부합니다. 고아 값을 제거하거나 표현식을 수정하십시오.
DynamoDB S3 가져오기 실패 — 잘못된 형식 수정
객체가 선언된 InputFormat 또는 압축과 일치하지 않거나 항목에 기본 키가 부족한 경우 S3에서 DynamoDB 가져오기가 실패합니다.
"Size of hashkey has exceeded the maximum size limit of 2048 bytes" — 수정
DynamoDB 파티션 키는 최대 2,048바이트, 정렬 키는 1,024바이트일 수 있습니다. 둘 중 하나를 초과하면 쓰기가 거부됩니다. 키를 다시 디자인하는 방법은 다음과 같습니다.
DynamoDB GSI "Does Not Project" 속성 — 해결
GSI는 키 속성과 그 프로젝션만 반환하므로, 그 밖의 속성을 GSI에서 쿼리하면 실패합니다. 프로젝션이나 요청을 바꾸세요 — 방법을 설명합니다.
"중첩 수준이 지원되는 제한을 초과했습니다." — DynamoDB 32레벨 수정
DynamoDB는 맵 및 목록 중첩을 32개 수준으로 제한합니다. 더 깊은 문서에서는 "중첩 수준이 지원되는 제한을 초과했습니다."라는 메시지가 표시됩니다. 32개 수준 아래의 중첩된 지도와 목록을 평면화합니다.
"Segment must be less than TotalSegments" - 병렬 스캔 수정
병렬 스캔에는 0 ≤ Segment < TotalSegments가 필요하며 둘 다 함께 전송해야 합니다. 각 작업자에게 0부터 TotalSegments - 1까지 고유한 Segment를 제공합니다.
DynamoDB "Cannot Specify AttributesToGet When Select Is COUNT" — 수정
DynamoDB는 ProjectionExpression 또는 AttributesToGet을 사용하여 Select=COUNT를 설정하는 쿼리 또는 스캔을 거부합니다. COUNT는 숫자를 반환하므로 투영을 삭제합니다.
DynamoDB 스트림 "제공된 ARN이 유효하지 않습니다" — 수정
DynamoDB 스트림은 /stream/latest와 같은 잘못된 형식 또는 자리 표시자 스트림 ARN을 거부합니다. DescriptionTable이 반환하는 실제 RecentStreamArn을 그대로 전달합니다.
"거래 요청에는 한 항목에 대한 여러 작업이 포함될 수 없습니다" — 수정
DynamoDB는 두 작업이 동일한 기본 키를 대상으로 하는 경우 TransactWriteItems 호출을 거부합니다. 중복 항목을 축소하거나 하나를 별도의 쓰기로 이동하세요.
DynamoDB TransactWriteItems 100개 작업 제한 — 수정
TransactWriteItems는 100개 작업으로 제한됩니다. 그 이후에는 TransactItems 길이에 대해 ValidationException이 발생합니다. 분할하거나 호출당 25개의 BatchWriteItem을 사용하세요.
DynamoDB TTL 속성은 Number여야 합니다 — 원인 및 해결
DynamoDB TTL은 TTL 속성이 Unix 에포크 초 단위의 Number인 항목만 만료시킵니다. 문자열, 밀리초 값, 또는 없는 속성은 절대 만료되지 않습니다.
DynamoDB "표현식은 비워둘 수 없습니다." — 수정
DynamoDB는 빈 문자열로 전달된 표현식 매개변수를 거부합니다. 보낼 내용이 없으면 FilterExpression 또는 UpdateExpression을 완전히 생략하세요.
"ExpressionAttributeNames에 잘못된 키가 포함되어 있습니다: 구문 오류" — 수정
DynamoDB는 자리 표시자 키가 `#name` 구문을 위반하는 ExpressionAttributeNames 맵을 거부합니다. 명명 규칙 및 실제 이름이 속하는 위치.
"Two document paths overlap with each other" (DynamoDB) — 해결
DynamoDB는 부모 경로와 그 안에 중첩된 경로를 함께 설정하는 UpdateExpression을 거부합니다. 자식을 부모에 접어 넣거나, 두 번의 업데이트로 나누세요.
"The document path provided in the update expression is invalid" — 해결
잘못된 문서 경로는 중첩 속성의 부모가 존재하지 않거나 map이 아니라는 뜻입니다. DynamoDB는 부모를 자동으로 만들지 않으므로 먼저 만들어야 합니다.
"업데이트 표현식의 피연산자에 잘못된 데이터 유형이 있습니다" — 수정
업데이트 피연산자의 유형이 저장된 것과 일치하지 않습니다. 숫자가 아닌 경우 ADD, 목록이 아닌 경우 list_append, 일치하지 않는 집합입니다.
DynamoDB IdempotentParameterMismatchException — 원인 및 해결
TransactWriteItems는 10분 멱등성 창 안에서 다른 페이로드로 ClientRequestToken을 재사용하는 재시도를 거부합니다. 해결 방법을 설명합니다.
"글로벌 보조 인덱스에서는 일관된 읽기가 지원되지 않습니다" — 수정
ConsistencyRead true를 사용하여 GSI를 쿼리하면 ValidationException이 발생합니다. GSI는 최종적 일관된 읽기만 제공합니다. 플래그를 삭제하거나 기본 테이블을 읽으십시오.
DynamoDB DuplicateItemException (PartiQL INSERT) — 원인 및 해결
PartiQL INSERT는 기본 키가 이미 존재하면 DuplicateItemException으로 실패합니다. PutItem과 달리 결코 덮어쓰지 않으므로 UPDATE나 PutItem을 쓰세요.
"소스에서 예기치 않은 오류 발생"(DynamoDB PartiQL) — 수정
대시나 기타 특수 문자가 포함된 테이블 이름이 FROM에서 큰따옴표로 묶이지 않은 경우 PartiQL은 "소스에서 예기치 않은 오류"를 발생시킵니다. 하나의 따옴표 쌍이 문제를 해결합니다.
boto3 "Parameter validation failed" (ParamValidationError) — 해결
botocore는 요청이 DynamoDB에 도달하기도 전에 ParamValidationError를 발생시킵니다 — 보통 client와 resource 타입 혼동입니다. 메시지를 읽고 고치는 방법을 설명합니다.
"제공된 시작 키가 잘못되었습니다."(DynamoDB) — 수정
DynamoDB는 페이지를 매기는 테이블이나 인덱스의 키 스키마와 일치하지 않는 ExclusiveStartKey를 거부합니다. LastEvaluatedKey를 그대로 전달합니다.
처리량 및 제한(throttling) 오류 (11)
DynamoDB ProvisionedThroughputExceededException — 원인 및 해결
DynamoDB는 읽기나 쓰기가 테이블 또는 GSI의 프로비저닝된 용량을 넘을 때 ProvisionedThroughputExceededException을 던집니다. 무엇이 바닥났는지와 그 해결책을 설명합니다.
DynamoDB ThrottlingException — 원인 및 수정
ThrottlingException은 종종 CreateTable과 같은 제어 영역 호출에서 요청 속도가 한도를 초과했음을 의미합니다. 지수 백오프로 재시도하고 속도를 줄입니다.
DynamoDB ItemCollectionSizeLimitExceededException — 원인 및 수정
이 오류는 로컬 보조 인덱스(항목 컬렉션(하나의 파티션 키를 공유하는 모든 항목))가 10GB를 초과한 테이블에만 발생합니다.
DynamoDB RequestLimitExceeded — 원인 및 해결
RequestLimitExceeded는 계정 수준 속도 한도입니다 — 온디맨드 기본값은 초당 40,000 읽기 및 쓰기 요청 유닛입니다. Service Quotas에서 올리세요.
DynamoDB TransactionConflectException — 원인 및 해결 방법
TransactionConflectException은 다른 트랜잭션이 이미 동일한 항목을 다루고 있음을 의미합니다. 일시적입니다. 백오프로 재시도하고 트랜잭션을 작게 유지하세요.
"Provisioned throughput decreases are limited within a given day" — 해결
DynamoDB는 UTC 하루에 테이블의 프로비저닝된 용량을 낮출 수 있는 횟수를 제한합니다. 할당량 계산과 이 UpdateTable 오류를 우회하는 방법을 설명합니다.
DynamoDB On-Demand Throughput Exceeded — 원인 및 해결
온디맨드 테이블도 스로틀링됩니다 — 설정된 최대 처리량, 이전 피크의 두 배를 넘는 램프업, 또는 테이블 할당량. 상한을 올리는 방법을 설명합니다.
용량에도 불구하고 DynamoDB가 제한됨 - 핫 파티션 수정
DynamoDB는 각 물리적 파티션이 3,000 RCU 및 1,000 WCU로 제한되기 때문에 여분의 테이블 용량이 있어도 하나의 핫 파티션 키를 제한합니다.
DynamoDB TransactionInProgressException — 원인 및 수정
TransactWriteItems 재시도는 아직 실행 중인 시도의 ClientRequestToken을 재사용했습니다. 백오프를 사용하여 계속 재시도하고 5초가 지난 시간 제한을 조정하세요.
DynamoDB InternalServerError(HTTP 500) - 수행할 작업
DynamoDB의 HTTP 500은 일시적인 서비스 측 오류이므로 재시도해도 안전합니다. 하지만 실패한 쓰기가 여전히 적용될 수 있습니다. 백오프로 재시도하세요. 실패를 가정하기 전에 쓰기를 확인하십시오.
DynamoDB ReplicatedWriteConflectException — 원인 및 수정
다중 리전 강력하게 일관된 글로벌 테이블에서 다른 리전이 동일한 항목을 수정하면 쓰기가 거부됩니다. 재시도 가능합니다. 방법은 다음과 같습니다.
테이블 및 리소스 오류 (19)
DynamoDB ResourceNotFoundException — 원인 및 수정
ResourceNotFoundException은 호출하는 지역 및 계정에 테이블이나 인덱스가 없음을 의미합니다. 이름, 지역, 자격 증명을 확인하세요.
DynamoDB ResourceInUseException("테이블이 이미 존재합니다.") — 수정
ResourceInUseException은 테이블이 이미 존재하거나 여전히 생성 중, 업데이트 중 또는 삭제 중임을 의미합니다. 조치를 취하기 전에 DescriptionTable을 사용하여 상태를 확인하세요.
DynamoDB LimitExceededException — 원인 및 수정
LimitExceededException은 동시 CreateTable, UpdateTable 또는 DeleteTable 호출이 너무 많거나 적중 계정 제한이 있음을 의미합니다. 제어 영역 호출을 직렬화하고 계정 할당량을 유지하세요.
"테이블에 지정된 인덱스가 없습니다" — 수정
DynamoDB는 IndexName이 해당 테이블에 존재하지 않거나, 철자가 틀리거나, GSI가 아직 ACTIVE가 아니기 때문에 호출을 거부합니다. 테이블에서 IndexName을 확인하고 GSI가 ACTIVE인지 확인하세요.
DynamoDB BackupNotFoundException — 원인 및 수정
DynamoDB BackupNotFoundException은 전달한 BackupArn과 일치하는 백업이 없음을 의미합니다. 일반적으로 잘못된 ARN, 삭제되거나 만료된 백업 또는 잘못된 리전입니다.
DynamoDB ReplicaNotFoundException — 원인 및 수정
ReplicaNotFoundException은 업데이트 중인 리전 복제본이 글로벌 테이블(잘못된 리전, 제거된 복제본 또는 경합)에 없음을 의미합니다.
"생성 중인 GSI를 수정하려고 시도하는 중" — 수정
DynamoDB는 글로벌 보조 인덱스가 아직 구축되는 동안 구조적 변경을 차단합니다. IndexStatus가 ACTIVE에 도달할 때까지 기다리거나 변경 사항을 순서대로 지정하세요.
DynamoDB ExportTableToPointInTime — PITR 미활성화 해결
ExportTableToPointInTime은 원본 테이블에 특정 시점 복구가 켜져 있어야 하며, 그렇지 않으면 PointInTimeRecoveryUnavailableException을 던집니다. 명령 하나로 해결합니다.
DynamoDB 전역 테이블 버전 불일치 — 원인 및 수정
비어 있지 않은 테이블, 일치하지 않는 키 스키마 또는 GSI, 2017 및 2019 API 버전 혼합 등 복제본이 정렬되지 않으면 전역 테이블 생성이 실패합니다.
DynamoDB LSI 항목 수집 10GB 제한 — 원인 및 수정
Local Secondary Index가 있는 테이블은 각 항목 컬렉션을 10GB로 제한합니다. 이를 초과하면 쓰기가 실패합니다. ItemCollectionMetrics를 모니터링하고 다시 샤딩합니다.
DynamoDB가 스트림에 액세스할 수 없음 — 스트림이 활성화되지 않음 수정
소비자가 스트림이 꺼진 테이블에서 DynamoDB 스트림을 읽거나 오래된 ARN을 사용했습니다. Streams를 활성화하고 현재 RecentStreamArn을 가리킵니다.
DynamoDB TableAlreadyExistsException / "테이블이 이미 존재합니다." — 수정
복원하면 TableAlreadyExistsException이 발생합니다. CreateTable 및 ImportTable은 ResourceInUseException을 보고합니다. 대상 이름이 이미 사용되었으므로 새 이름을 선택하세요.
DynamoDB Streams ExpiredIteratorException — 원인 및 해결
DynamoDB Streams 샤드 이터레이터는 15분 동안 유효합니다. 그 뒤에 쓰면 GetRecords가 ExpiredIteratorException을 던집니다. 데이터 손실 없이 재개하는 방법을 설명합니다.
DynamoDB 스트림 TrimmedDataAccessException — 원인 및 수정
스트림 레코드는 24시간 동안 유지되므로 그보다 오래된 체크포인트에서는 TrimmedDataAccessException이 발생합니다. TRIM_HORIZON에서 재개하고 테이블에서 조정합니다.
DynamoDB BackupInUseException — 원인 및 수정
DynamoDB BackupInUseException은 동일한 테이블에서 다른 백업 작업이 아직 실행 중임을 의미합니다. 완료될 때까지 기다린 후 통화를 다시 시도하세요.
DynamoDB InvalidRestoreTimeException — 원인 및 수정
InvalidRestoreTimeException은 RestoreDateTime이 최대 35일의 테이블 PITR 기간을 벗어나는 것을 의미합니다. 테이블의 PITR 기간 내에서 RestoreDateTime을 선택합니다(최대 35일).
DynamoDB PointInTimeRecoveryUnavailableException — 수정
PITR이 활성화된 적이 없는 테이블에서 특정 시점 복원을 시도했습니다. 지금 연속 백업을 활성화하고 오늘의 데이터에 대해 주문형 백업을 사용하세요.
DynamoDB GlobalTableNotFoundException — 원인 및 수정
GlobalTableNotFoundException은 레거시 전역 테이블 API가 테이블(일반적으로 UpdateTable을 통해 관리되는 2019.11.21 전역 테이블)을 볼 수 없음을 의미합니다.
DynamoDB ReplicaAlreadyExistsException — 원인 및 수정
DynamoDB에 이미 글로벌 테이블에 복제본 리전을 추가하도록 요청했습니다. 먼저 복제 그룹을 설명하고 복제본 관리를 멱등성으로 만듭니다.
인증 및 구성 오류 (13)
"not authorized to perform dynamodb:..." — AccessDeniedException 수정
DynamoDB AccessDeniedException은 IAM 자격 증명이 메시지에 명명된 작업에 대해 승인되지 않았음을 의미합니다. IAM 정책을 읽고 수정하는 방법
"ConfigError: 구성에 지역이 누락되었습니다" — DynamoDB 수정
AWS SDK는 DynamoDB 요청을 어느 리전으로 보낼지 알아낼 수 없습니다. AWS_REGION을 통해 클라이언트에서 설정하거나 AWS 구성에서 설정합니다. 각 옵션은 다음과 같습니다.
"요청에 포함된 보안 토큰이 유효하지 않습니다." — DynamoDB 수정
이 UnrecognizedClientException은 AWS 자격 증명이 잘못되었거나 만료되었거나 선택되지 않았음을 의미합니다. 액세스 키, 세션 토큰 만료, SDK가 로드한 프로필을 확인하세요.
DynamoDB IncompleteSignatureException — 원인 및 수정
IncompleteSignatureException은 SigV4 서명의 형식이 잘못되었음을 의미합니다. 일반적으로 수동으로 서명하거나 Authorization 헤더를 다시 작성한 프록시입니다.
"요청에 포함된 보안 토큰이 만료되었습니다." — DynamoDB 수정
ExpiredTokenException은 임시 STS, SSO 또는 위임된 역할 자격 증명이 시간 초과되었음을 의미합니다. aws sso login을 다시 실행하고 오래된 AWS_SESSION_TOKEN을 삭제합니다.
"자격 증명을 찾을 수 없습니다"(boto3/DynamoDB) — 수정
boto3는 공급자 체인에 AWS 자격 증명을 제공하는 것이 없을 때(env var, 프로필, 인스턴스 역할 없음) NoCredentialsError를 발생시킵니다.
"우리가 계산한 요청 서명이 일치하지 않습니다" — 수정
SigV4 서명이 실패하면 DynamoDB는 SignatureDoesNotMatch가 아닌 InvalidSignatureException을 반환합니다. 일반적으로 컴퓨터에 잘못된 비밀 키 또는 시계 왜곡이 있습니다.
"자격 증명은 유효한 리전으로 범위가 지정되어야 합니다." — DynamoDB 수정
이 SigV4 오류는 자격 증명 범위의 지역이 실제로 호출한 지역과 일치하지 않음을 의미합니다. 클라이언트 및 엔드포인트 지역을 정렬하는 방법
"InvalidSignatureException: 서명이 만료되었습니다" — DynamoDB 수정
DynamoDB는 서명된 타임스탬프가 AWS 서버 시간보다 5분 이상 빠른 요청을 거부합니다. 거의 항상 클라이언트 시계 오차가 발생합니다. 이를 해결하는 방법은 다음과 같습니다.
"인증 토큰 누락" — DynamoDB 오류 수정
DynamoDB의 MissingAuthenticationTokenException은 잘못된 엔드포인트 URL이나 경로 또는 서명되지 않은 요청을 의미합니다. 엔드포인트 URL, 경로를 확인하고 요청이 SigV4로 서명되었는지 확인하세요.
"모든 공급자로부터 자격 증명을 로드할 수 없습니다"(DynamoDB) — 수정
JavaScript v3용 AWS SDK에서는 전체 자격 증명 체인이 비어 있으면 CredentialsProviderError가 발생합니다. 체인이 해결되는 방법 및 각 수정 사항.
"The SSO session associated with this profile has expired" — 수정
만료된 IAM Identity Center 토큰은 DynamoDB에 대한 AWS CLI 및 SDK 호출을 중단합니다. aws sso login을 실행하고, 충분하지 않은 경우 오래된 ~/.aws/sso/cache를 삭제합니다.
"The config profile could not be found" (AWS CLI 및 boto3) — 수정
~/.aws/config에서 명명된 프로필이 누락되면 AWS CLI 및 boto3에서 ProfileNotFound가 발생합니다. 세 가지 일반적인 원인과 각각에 대한 해결 방법입니다.
DynamoDB Local 및 설정 오류 (8)
"DynamoDB 로컬 프로세스를 시작할 수 없습니다" — 수정
DynamoDB Local을 시작하지 못했습니다. 일반적으로 누락/호환되지 않는 Java 런타임, 이미 사용 중인 포트 또는 잘못된 설치 경로입니다. Java 런타임, 포트 충돌, 설치 경로를 확인하세요.
"Could not connect to DynamoDB Local" (ECONNREFUSED) — 수정
DynamoDB Local에 대한 ECONNREFUSED는 수신 대기 중인 항목이 없음을 의미합니다. 일반적으로 에뮬레이터가 실행되고 있지 않거나, 포트가 잘못되었거나, SDK가 실제 AWS에 도달하고 있습니다.
"Could not connect to the endpoint URL" (DynamoDB) — 수정
botocore는 DynamoDB에 연결할 수 없으면 EndpointConnectionError를 발생시킵니다. 일반적으로 잘못된 엔드포인트 URL, DynamoDB Local이 실행되지 않거나 잘못된 리전입니다.
DynamoDB 로컬 "주소가 이미 사용 중"(포트 8000) — 수정
DynamoDB Local은 이미 포트 8000을 소유한 경우 java.net.BindException을 발생시킵니다. 프로세스를 찾고, 포트를 해제하거나, 다른 포트에서 Local을 시작하는 방법입니다.
DynamoDB 로컬 "Failed to load native library sqlite4java" — 수정
DynamoDB Local은 시작 시 잘못된 java.library.path 또는 Apple Silicon 아치 불일치로 인해 sqlite4java에 대한 UnsatisfiedLinkError로 인해 종료됩니다.
"HTTP 요청을 실행할 수 없습니다"(DynamoDB, Java SDK) — 수정
엔드포인트에 도달할 수 없으면 Java용 AWS SDK가 HTTP 요청을 실행할 수 없다는 메시지와 함께 실패합니다. DynamoDB 로컬 다운, 잘못된 포트 또는 Docker 네트워킹.
"존재하지 않는 테이블에서 작업을 수행할 수 없습니다"(DynamoDB 로컬) — 수정
DynamoDB Local은 각 자격 증명과 리전 쌍에 자체 데이터베이스를 제공하므로 생성한 테이블이 보이지 않을 수 있습니다. 공유하려면 -sharedDb로 Local을 실행하세요.
DynamoDB 로컬 UnsupportedClassVersionError — 수정
DynamoDB Local 2.6.0 이상에는 Java 17 이상이 필요합니다. 이전 JRE에서는 JVM이 로드를 거부합니다. 최신 JDK를 설치하거나 Docker 이미지를 실행하세요.
이 메시지들을 어떻게 검증했나요
문서는 구현 내용을 말로 옮긴 것이고, 그 표현은 시간이 지나면서 어긋납니다. 이 페이지들에 인용된 모든 오류 메시지는 실패하는 호출을 실제 AWS DynamoDB 서비스에 직접 실행하고 돌아온 내용을 한 글자씩 그대로 기록한 것입니다 — AWS 문서에서 복사한 것이 아닙니다.
DynamoDB Local이 아닙니다. 에뮬레이터는 편리하지만, AWS는 에뮬레이터가 서비스와 같은 문구로 오류를 표현한다고 보장하지 않습니다 — 실제로 확인해 보니 메시지의 절반 이상이 달랐습니다. 그 차이를 알아둘 가치가 있는 경우에는 페이지에 둘 다 표시합니다.
손을 댄 부분은 오류가 아니라 요청을 설명하는 부분뿐입니다. 테이블 이름과, 서비스가 그대로 되돌려 주는 페이로드 사본입니다. 어떤 페이지든 서비스가 반환한 적 없는 문자열을 인용하면 테스트가 빌드를 실패시킵니다 — 우리 페이지 중 하나가 아무도 코드를 실행해 보지 않은 채 지어낸 메시지를 몇 달 동안 인용했기 때문에 만든 장치입니다.
14개 예외 유형에 걸친 메시지 58개: 55개는 실제 서비스에서 캡처했고, 2개는 요청이 전송되기 전에 SDK가 거부했으며, 1개는 DynamoDB Local 자체의 문구를 다룹니다. 6개에는 에뮬레이터가 같은 실패를 어떻게 표현하는지에 대한 설명이 붙어 있습니다.
- 실제 서비스
- Amazon DynamoDB (live service, us-east-1)
- 에뮬레이터(비교용)
- DynamoDB Local (amazon/dynamodb-local)
- JavaScript SDK
- @aws-sdk/client-dynamodb 3.1096.0
- Python SDK
- boto3 1.43.81 on Python 3.14.7
- Node.js
- v24.20.0