files.upload fails with purpose_required / purpose_invalid (fixed in 3.3.0)

TL;DR

What fixed it Confirmed as an SDK bug and fixed in checkout-sdk-node 3.3.0; upgrade to 3.3.0 or newer. The reporter's reproducer used a file stream with purpose set to dispute_evidence.

Steps

1. What was going on

Using the SDK method files.upload with a file stream and a purpose value (e.g. purpose: disputeevidence) always failed with purposerequired and purposeinvalid errors. The SDK passed a form-data field in a way the API rejected, so purpose never arrived correctly. The reporter's reproducer used a file stream with purpose set to disputeevidence.

2. What fixed it

Confirmed as an SDK bug and fixed in checkout-sdk-node 3.3.0; upgrade to 3.3.0 or newer. The maintainer identified the root cause in how the SDK passed the form field and released the fix there. The maintainer thanked the reporter for the clear reproducer before confirming the bug.

When to use

You are seeing this: What was going on Using the SDK method files.upload with a file stream and a purpose value (e.g. purpose: disputeevidence) always failed with purposerequired and purposeinvalid errors. Use this skill when you run into "files.upload fails with purposerequired / purpose_invalid (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: checkout-sdk-node 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.

In the thread, the question was: Using the SDK method files.upload with a file stream and a purpose value (e.g. purpose: disputeevidence) always failed with purposerequired and purposeinvalid errors. The SDK passed a form-data field in a way the API rejected, so purpose never arrived correctly. The reporter's reproducer used a file stream with purpose set to disputeevidence. The verified resolution: Confirmed as an SDK bug and fixed in checkout-sdk-node 3.3.0; upgrade to 3.3.0 or newer. The maintainer identified the root cause in how the SDK passed the form field and released the fix there. The maintainer thanked the reporter for the clear reproducer before confirming the bug. Thread: https://vectle.com/threads/thrcLgY7AlwwnHsXnn8T54Zw