boto3: Parameter validation failed (ParamValidationError)

TL;DR — botocore.exceptions.ParamValidationError, herhangi bir istek gönderilmeden önce makinenizde fırlatılır — ilettiğiniz argümanlar işlemin beklenen şekliyle eşleşmiyor. DynamoDB kodunda neredeyse her zaman bir client-vs-resource karışıklığıdır: düşük seviyeli client, DynamoDB-JSON ({'S': 'abc'}, dizeler olarak sayılar) ister, Table kaynağı yerel Python türlerini ister. Stili çağırdığınız arabirime eşleştirin.

Ne anlama gelir

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

# what the engine actually returns, reproduced against boto3 1.43.67 on Python 3.11.15:
ParamValidationError: Parameter validation failed:
Invalid type for parameter Item.price.N, value: 42, type: <class 'int'>, valid types: <class 'str'>

botocore, her çağrıyı imzalamadan önce hizmetin API modeline karşı doğrular. Buradaki bir hata bir ClientError değildir — DynamoDB isteği hiç görmedi — bu yüzden except ClientError onu yakalamaz ve hiç ağ gidiş-dönüşü olmadı. Mesaj, başarısız olan tam parametre yolunu ve beklediği türü adlandırır.

Neden olur

• Düşük seviyeli istemciye iletilen yerel Python değerleri — boto3.client('dynamodb') çıplak DynamoDB JSON konuşur: her öznitelik tür etiketli bir map'tir ve N değerleri dizelerdir ({'N': '42'}, 42 değil).
• Table kaynağına iletilen DynamoDB-JSON — ters karışıklık: boto3.resource('dynamodb').Table(...) düz Python değerleri bekler ve marshal işlemini sizin için yapar.
• Bir dizenin beklendiği yerde koşul nesneleri — sorgu sayfalayıcısının KeyConditionExpression'ı bir dize ifadesi kabul eder; Key('pk').eq(...) nesneleri orada doğrulamayı geçemez.
• Yanlış yazılmış ya da desteklenmeyen bir parametre adı — bilinmeyen anahtarlar doğrulamayı geçemez; güncel olmayan bir botocore, paketlenmiş modelinden sonra API'ye eklenen parametreleri de reddedebilir.

Nasıl düzeltilir

1. Bir arabirim seçin ve tür stilini tutarlı kullanın:

   # 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'}})

   KopyalaKopyalandı

2. Sayfalayıcılarla dize ifadeleri kullanın — KeyConditionExpression='pk = :p' artı ExpressionAttributeValues ya da Table kaynağını LastEvaluatedKey ile elle sayfalayın.

3. Mesajdaki parametre yolunu okuyun — Item.price.N, tam olarak hangi özniteliğin ve hangi tür etiketinin başarısız olduğunu söyler; tahmin etmek yerine o alanı düzeltin.

4. "Unknown parameter" hataları için botocore'u yükseltin — parametre gerçekse ama doğrulama modeliniz ondan önceyse, pip install -U boto3 botocore.

5. Onu hizmet hatalarından ayrı yakalayın:

   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
       ...

   KopyalaKopyalandı

DynamoDB-JSON'u elle yazmak, bu tür etiketlerinin yanlış gittiği yerdir — DynamoDB JSON dönüştürücüsü, yerel JSON ile tür etiketli kablo biçimi arasında çeviri yapar ve DynoTable masaüstü uygulaması, öğeleri sizin için ele alınan marshal ile düzenler.

Nasıl yeniden oluşturulur

boto3'ün Key eşlemesi beklediği yere bir string geçirin. Denetim tamamen istemci tarafındadır:

import boto3
boto3.client('dynamodb', region_name='us-east-1').get_item(TableName='repro', Key='not-a-dict')

Gerçek çıktı:

ParamValidationError: Parameter validation failed:
Invalid type for parameter Key, value: not-a-dict, type: <class 'str'>, valid types: <class 'dict'>

botocore parametrenin adını, aldığı değeri, onun türünü ve istediği türü verir — tek mesajda dört bilgi. AWS'ye hiçbir şey gönderilmedi, dolayısıyla kapasite tüketilmedi ve yeniden denenecek bir şey yok; düzeltme her zaman çağrı yerindedir.

İlgili hatalar

• Float types are not supported — boto3'ün diğer istemci tarafı tür reddi (Decimal kullanın).
• ValidationException: One or more parameter values were invalid — istek gerçekten çıktığında sunucu tarafı muadili.
• Öğrenin: DynamoDB JSON & marshalling

Kaynaklar

• Error handling — Boto3 documentation
• AttributeValue — Amazon DynamoDB API Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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

2026-07-26 tarihinde boto3 1.43.56 / botocore 1.43.56 ile yeniden üretildi — yukarıdaki çıktı birebir alınmıştır.