boto3: Parameter validation failed (ParamValidationError)

TL;DR — botocore.exceptions.ParamValidationError dimunculkan di mesin Anda, sebelum permintaan apa pun dikirim — argumen yang Anda teruskan tidak cocok dengan bentuk yang diharapkan operasi. Dalam kode DynamoDB ini hampir selalu kekeliruan client-vs-resource: client low-level menginginkan DynamoDB-JSON ({'S': 'abc'}, angka sebagai string), resource Table menginginkan tipe Python native. Cocokkan gaya dengan interface yang Anda panggil.

Apa artinya

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

botocore memvalidasi setiap panggilan terhadap model API layanan sebelum menandatanganinya. Kegagalan di sini bukan ClientError — DynamoDB tidak pernah melihat permintaan — jadi except ClientError tidak akan menangkapnya, dan tidak ada perjalanan bolak-balik jaringan yang terjadi. Pesan menyebut path parameter tepat yang gagal dan tipe yang diharapkannya.

Mengapa terjadi

• Nilai Python native diteruskan ke client low-level — boto3.client('dynamodb') berbicara DynamoDB JSON mentah: setiap atribut adalah map bertag-tipe dan nilai N adalah string ({'N': '42'}, bukan 42).
• DynamoDB-JSON diteruskan ke resource Table — kekeliruan sebaliknya: boto3.resource('dynamodb').Table(...) mengharapkan nilai Python biasa dan melakukan marshalling untuk Anda.
• Objek kondisi di mana string diharapkan — KeyConditionExpression paginator kueri menerima string expression; objek Key('pk').eq(...) gagal validasi di sana.
• Nama parameter salah ketik atau tidak didukung — kunci yang tidak dikenal gagal validasi; botocore usang juga dapat menolak parameter yang ditambahkan ke API setelah model yang dibundel.

Cara memperbaikinya

1. Pilih satu interface dan gunakan gaya tipenya secara konsisten:

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

2. Gunakan string expression dengan paginator — KeyConditionExpression='pk = :p' ditambah ExpressionAttributeValues, atau paginasi resource Table secara manual dengan LastEvaluatedKey.

3. Baca path parameter dalam pesan — Item.price.N memberi tahu Anda persis atribut mana dan tag tipe mana yang gagal; perbaiki satu field itu daripada menebak.

4. Tingkatkan botocore untuk kegagalan "Unknown parameter" — jika parameter nyata tetapi model validasi Anda mendahuluinya, pip install -U boto3 botocore.

5. Tangkap terpisah dari kesalahan layanan:

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

Menulis DynamoDB-JSON secara manual adalah tempat tag tipe ini salah — DynamoDB JSON converter menerjemahkan antara JSON native dan format wire bertag-tipe, dan aplikasi desktop DynoTable mengedit item dengan marshalling ditangani untuk Anda.

Kesalahan terkait

• Float types are not supported — penolakan tipe sisi-klien lain boto3 (gunakan Decimal).
• ValidationException: One or more parameter values were invalid — padanan sisi-server setelah permintaan keluar.
• Pelajari: DynamoDB JSON & marshalling

References

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

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.