boto3: Parameter validation failed (ParamValidationError)

요약 — botocore.exceptions.ParamValidationError는 요청이 보내지기 전에 여러분의 머신에서 발생합니다 — 전달한 인수가 작업이 예상하는 형태와 일치하지 않습니다. DynamoDB 코드에서 이는 거의 항상 클라이언트 대 리소스 혼동입니다: 저수준 client는 DynamoDB-JSON({'S': 'abc'}, 숫자는 문자열)을 원하고, Table 리소스는 네이티브 Python 타입을 원합니다. 스타일을 호출하는 인터페이스와 일치시키세요.

무엇을 의미하나요

botocore.exceptions.ParamValidationError: Parameter validation failed:
Invalid type for parameter Item.price.N, value: 42, type: <class 'int'>,
valid types: <class 'str'>

botocore는 서명 전에 모든 호출을 서비스의 API 모델에 대해 검증합니다. 여기서의 실패는 ClientError가 아닙니다 — DynamoDB는 요청을 전혀 보지 못했습니다 — 그래서 except ClientError가 이를 잡지 못하며, 네트워크 왕복도 일어나지 않았습니다. 메시지가 실패한 정확한 파라미터 경로와 예상한 타입을 지정합니다.

왜 발생하나요

네이티브 Python 값이 저수준 클라이언트에 전달됨 — boto3.client('dynamodb')는 원시 DynamoDB JSON을 사용합니다: 모든 속성은 타입 태그가 있는 map이고 N 값은 문자열({'N': '42'}, 42가 아님)입니다.
DynamoDB-JSON이 Table 리소스에 전달됨 — 반대 혼동: boto3.resource('dynamodb').Table(...)은 일반 Python 값을 예상하고 마셜링을 대신 합니다.
문자열이 예상되는 곳의 Condition 객체 — 쿼리 페이지네이터의 KeyConditionExpression은 문자열 표현식을 받습니다. Key('pk').eq(...) 객체는 거기서 검증에 실패합니다.
오타가 있거나 지원되지 않는 파라미터 이름 — 알 수 없는 키는 검증에 실패합니다. 오래된 botocore는 번들된 모델 이후 API에 추가된 파라미터를 거부할 수도 있습니다.

어떻게 고치나요

하나의 인터페이스를 골라 그 타입 스타일을 일관되게 사용하세요:

# Table resource — native Python types
table = boto3.resource('dynamodb').Table('orders')
table.put_item(Item={'pk': 'ORDER#1', 'price': Decimal('42')})

# Low-level client — DynamoDB-JSON, numbers as strings
client = boto3.client('dynamodb')
client.put_item(TableName='orders',
                Item={'pk': {'S': 'ORDER#1'}, 'price': {'N': '42'}})

페이지네이터에는 문자열 표현식을 사용하세요 — KeyConditionExpression='pk = :p'와 ExpressionAttributeValues, 또는 LastEvaluatedKey로 Table 리소스를 수동으로 페이징하세요.
메시지의 파라미터 경로를 읽으세요 — Item.price.N은 어느 속성과 어느 타입 태그가 실패했는지 정확히 알려줍니다. 추측하는 대신 그 필드 하나를 고치세요.
"Unknown parameter" 실패는 botocore를 업그레이드하세요 — 파라미터가 실제인데 검증 모델이 그보다 앞선다면 pip install -U boto3 botocore.

서비스 오류와 별도로 잡으세요:

from botocore.exceptions import ClientError, ParamValidationError
try:
    client.put_item(**kwargs)
except ParamValidationError as e:   # local: fix the call
    ...
except ClientError as e:            # remote: DynamoDB rejected it
    ...

DynamoDB-JSON을 수동으로 작성하는 것이 이러한 타입 태그가 잘못되는 곳입니다 — DynamoDB JSON 변환기는 네이티브 JSON과 타입 태그가 있는 와이어 형식 사이를 번역하고, DynoTable 데스크톱 앱은 마셜링이 대신 처리된 채로 항목을 편집합니다.

References

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

boto3: Parameter validation failed (ParamValidationError)

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

관련 오류

References