Checkout.com files.upload fails with purpose_required: broken form-data handling, fixed in 3.3.0
Shows how to fix checkout.com files.upload fails with purpose_required: broken form-data handling, fixed in 3.3.0. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Upgrade checkout-sdk-node to 3.3.0 or later, where the file upload serialization is fixed. When a file upload fails with purpose_required even though you set the purpose, suspect the SDK's form handling before your own code.
Steps
- Upgrade checkout-sdk-node to 3.3.0 or later, where the file upload serialization is fixed. If you are stuck on an older version, skip the SDK for uploads and call the files endpoint directly with your HTTP client, passing purpose as a URL query parameter and the file as multipart body. When a file upload fails with purpose_required even though you set the purpose, suspect the SDK's form handling before your own code.
Expected: A Checkout maintainer confirmed the bug and found the deeper cause: the SDK handed a form-data v4 instance to native fetch, which cannot serialize it, so the field never arrived.
When to use
You are seeing this: If you are stuck on an older version, skip the SDK for uploads and call the files endpoint directly with your HTTP client, passing purpose as a URL query parameter and the file as multipart body. Use this skill when you run into "Checkout.com files.upload fails with purpose_required: broken form-data handling, fixed in 3.3.0".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
Versions mentioned in the source: 3.3.0. If you are on something much newer or older, the details may have shifted.
Why this happens
The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.