boto3: Parameter validation failed (ParamValidationError)

In breve — botocore.exceptions.ParamValidationError viene sollevata sulla tua macchina, prima che qualsiasi richiesta venga inviata — gli argomenti che hai passato non corrispondono alla forma attesa dell'operazione. Nel codice DynamoDB è quasi sempre una confusione client-vs-resource: il client di basso livello vuole DynamoDB-JSON ({'S': 'abc'}, numeri come stringhe), la resource Table vuole tipi Python nativi. Abbina lo stile all'interfaccia che stai chiamando.

Cosa significa

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 valida ogni chiamata rispetto al modello API del servizio prima di firmarla. Un fallimento qui non è un ClientError — DynamoDB non ha mai visto la richiesta — quindi except ClientError non lo intercetterà, e nessun round trip di rete è avvenuto. Il messaggio nomina l'esatto percorso del parametro che è fallito e il tipo che si aspettava.

Perché succede

Valori Python nativi passati al client di basso livello — boto3.client('dynamodb') parla DynamoDB JSON grezzo: ogni attributo è una mappa con tag di tipo e i valori N sono stringhe ({'N': '42'}, non 42).
DynamoDB-JSON passato alla resource Table — la confusione inversa: boto3.resource('dynamodb').Table(...) si aspetta valori Python semplici e fa il marshalling per te.
Oggetti condizione dove è attesa una stringa — il KeyConditionExpression del paginator di query accetta un'espressione stringa; gli oggetti Key('pk').eq(...) falliscono la validazione lì.
Un nome di parametro con refuso o non supportato — le chiavi sconosciute falliscono la validazione; un botocore obsoleto può anche rifiutare parametri aggiunti all'API dopo il suo modello incluso.

Come risolverlo

Scegli un'interfaccia e usa il suo stile di tipo in modo coerente:

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

Usa espressioni stringa con i paginator — KeyConditionExpression='pk = :p' più ExpressionAttributeValues, oppure pagina manualmente la resource Table con LastEvaluatedKey.
Leggi il percorso del parametro nel messaggio — Item.price.N ti dice esattamente quale attributo e quale tag di tipo è fallito; correggi quel singolo campo invece di indovinare.
Aggiorna botocore per i fallimenti "Unknown parameter" — se il parametro è reale ma il tuo modello di validazione lo precede, pip install -U boto3 botocore.

Intercettala separatamente dagli errori di servizio:

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

Scrivere a mano il DynamoDB-JSON è dove questi tag di tipo si sbagliano — il convertitore DynamoDB JSON traduce tra JSON nativo e il formato wire con tag di tipo, e l'app desktop DynoTable modifica gli Item con il marshalling gestito per te.

Riproducilo

Passa una stringa dove boto3 si aspetta la mappa Key. Il controllo è interamente lato client:

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

Output reale:

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

botocore nomina il parametro, il valore che ha ricevuto, il suo tipo e il tipo che si aspettava — quattro informazioni in un solo messaggio. Non è stato inviato nulla ad AWS, quindi non è stata consumata capacità e non c'è nulla da ritentare; la correzione è sempre nel punto di chiamata.

Errori correlati

Float types are not supported — l'altro rifiuto di tipo lato client di boto3 (usa Decimal).
ValidationException: One or more parameter values were invalid — la controparte lato server una volta che la richiesta esce.
Impara: DynamoDB JSON & marshalling

Riferimenti

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.

Riprodotto il 2026-07-26 su boto3 1.43.56 / botocore 1.43.56 — l'output qui sopra è riportato alla lettera.