boto3: Parameter validation failed (ParamValidationError)

TL;DR — botocore.exceptions.ParamValidationError 是在你的機器上、在任何請求送出前拋出的 — 你傳入的引數不符操作預期的形狀。在 DynamoDB 程式碼中它幾乎總是 client 與 resource 的混淆：低階 client 想要 DynamoDB-JSON（{'S': 'abc'}、數字作為字串），而 Table resource 想要原生 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 值傳給低階 client — boto3.client('dynamodb') 說原始 DynamoDB JSON：每個屬性都是帶型別標記的 map，且 N 值是_字串_（{'N': '42'}，而非 42）。
將 DynamoDB-JSON 傳給 Table resource — 反向的混淆：boto3.resource('dynamodb').Table(...) 期望純 Python 值並為你完成 marshal。
在期望字串之處使用 Condition 物件 — 查詢 paginator 的 KeyConditionExpression 接受字串 expression；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'}})

對 paginator 使用字串 expression — KeyConditionExpression='pk = :p' 加上 ExpressionAttributeValues，或以 LastEvaluatedKey 手動分頁 Table resource。
閱讀訊息中的參數路徑 — 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 桌面應用程式為你處理好 marshal 來編輯項目。

References

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。

boto3: Parameter validation failed (ParamValidationError)

這是什麼意思

為什麼會發生

如何修正

相關錯誤

References