stagedUploadsCreate don't support FILE over 2MB

Technical Q&A
1

API version: 2025-10 (latest)

Input to stagedUploadsCreate:

{
  filename: 'additional-sitemap.xml',
  fileSize: '2204057',
  mimeType: 'application/xml',
  httpMethod: 'POST',
  resource: 'FILE'
}
  1. stagedUploadsCreate works fine, don’t return an userError.
  2. Uploading the file to `shopify-staged-uploads.storage.googleapis.com` responds with HTTP 400 and the following body:

Metadata part is too large.

Expected behaviour: Support up to 20MB staged uploads, like uploading manually in Admin.

2

Hi @ptz0n,

The error HTTP 400: Metadata part is too large is coming directly from the Google Cloud Storage bucket, not from Shopify’s internal file size validation.

You are likely not hitting the file size limit (2.2MB is fine), but rather a limit on the HTTP Headers or the Multipart Form Data structure of your POST request.

Since stagedUploadsCreate returns a set of parameters (policy, signature, Google Access ID, etc.), ensure the following in your upload script:

  1. Form Data Order: When constructing the FormData, make sure you append the parameters (fields) before you append the file. Some GCS endpoints are strict about the order (fields first, file last).

  2. No Extra Headers: Ensure your HTTP client (Axios, Fetch, etc.) is not injecting massive custom headers or trying to send the parameters as URL query strings instead of body fields.

  3. Content-Type: Verify that you are sending the request as multipart/form-data.

The error specifically means the “non-file” part of your payload (the metadata/headers) exceeds the allowable bytes for a GCS signed URL request.

Hope this points you in the right direction!