boto3: Parameter validation failed (ParamValidationError)

TL;DR — botocore.exceptions.ParamValidationError dilempar di mesin Anda, sebelum request apa pun terkirim — argumen yang Anda oper tidak cocok dengan bentuk yang diharapkan operasi tersebut. Di kode DynamoDB penyebabnya hampir selalu tertukarnya client dan resource: client low-level ingin DynamoDB-JSON ({'S': 'abc'}, angka sebagai string), sedangkan resource Table ingin tipe Python native. Sesuaikan gayanya dengan antarmuka 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'>

# 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 memvalidasi setiap panggilan terhadap model API layanan sebelum menandatanganinya. Kegagalan di sini bukan ClientError — DynamoDB tidak pernah melihat request-nya — jadi except ClientError tidak akan menangkapnya, dan tidak ada perjalanan jaringan yang terjadi. Pesannya menyebut persis path parameter yang gagal dan tipe yang diharapkannya.

Mengapa itu terjadi

• Nilai Python native dioper ke client low-level — boto3.client('dynamodb') berbicara DynamoDB JSON mentah: setiap atribut adalah map bertanda tipe dan nilai N berupa string ({'N': '42'}, bukan 42).
• DynamoDB-JSON dioper ke resource Table — kebalikannya: boto3.resource('dynamodb').Table(...) mengharapkan nilai Python biasa dan mengurus marshalling untuk Anda.
• Objek Condition di tempat yang mengharapkan string — KeyConditionExpression pada paginator query menerima expression berupa string; objek Key('pk').eq(...) gagal validasi di sana.
• Nama parameter salah ketik atau tidak didukung — key yang tidak dikenal gagal validasi; botocore yang usang juga bisa menolak parameter yang ditambahkan ke API setelah model bawaannya.

Bagaimana cara memperbaikinya

1. Pilih satu antarmuka dan pakai 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'}})

   SalinDisalin

2. Pakai expression berupa string dengan paginator — KeyConditionExpression='pk = :p' plus ExpressionAttributeValues, atau lakukan paginasi manual pada resource Table dengan LastEvaluatedKey.

3. Baca path parameter di dalam pesannya — Item.price.N memberi tahu persis atribut mana dan tanda tipe mana yang gagal; perbaiki field itu saja alih-alih menebak-nebak.

4. Upgrade botocore untuk kegagalan "Unknown parameter" — kalau parameternya memang ada tapi model validasi Anda lebih tua darinya, jalankan pip install -U boto3 botocore.

5. Tangkap terpisah dari error 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
       ...

   SalinDisalin

Menulis DynamoDB-JSON dengan tangan adalah tempat tanda-tanda tipe ini melenceng — konverter DynamoDB JSON menerjemahkan antara JSON native dan format wire bertanda tipe, dan aplikasi desktop DynoTable menyunting item dengan marshalling yang sudah diurus untuk Anda.

Cara mereproduksinya

Oper sebuah string di tempat boto3 mengharapkan pemetaan Key. Pemeriksaannya sepenuhnya di sisi klien:

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

Keluaran sebenarnya:

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

botocore menyebut parameternya, nilai yang ia terima, tipenya, dan tipe yang ia inginkan — empat fakta dalam satu pesan. Tidak ada apa pun yang terkirim ke AWS, jadi tidak ada kapasitas terpakai dan tidak ada yang perlu dicoba ulang; perbaikannya selalu di sisi pemanggil.

Kesalahan terkait

• Float types are not supported — penolakan tipe di sisi klien lainnya dari boto3 (pakai Decimal).
• ValidationException: One or more parameter values were invalid — padanannya di sisi server ketika request memang jadi terkirim.
• Pelajari: DynamoDB JSON & marshalling

Referensi

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

Direproduksi 2026-07-26 terhadap boto3 1.43.56 / botocore 1.43.56 — keluaran di atas dikutip apa adanya.