transloadit/uppy · error · Error

Failed request with status: ${res.status}. ${res.statusText}

Error message

Failed request with status: ${res.status}. ${res.statusText}

What it means

This generic Error is thrown from the catch branch of handleJSONResponse: the HTTP request already failed (non-OK status), and additionally the response body could not be parsed as JSON (e.g. an HTML error page from a proxy). The message combines status and statusText, and the original parse failure is attached via { cause }. It exists so callers still get a meaningful error when the server's error body is not JSON.

Source

Thrown at packages/@uppy/core/src/companion-client/RequestClient.ts:75

async function handleJSONResponse<ResJson>(res: Response): Promise<ResJson> {
  if (res.status === authErrorStatusCode) {
    throw new AuthError()
  }

  if (res.ok) {
    return res.json()
  }

  let errMsg = `Failed request with status: ${res.status}. ${res.statusText}`
  let errData: any
  try {
    errData = await res.json()

    if (errData.message) errMsg = `${errMsg} message: ${errData.message}`
    if (errData.requestId) errMsg = `${errMsg} request-Id: ${errData.requestId}`
  } catch (cause) {
    // if the response contains invalid JSON, let's ignore the error data
    throw new Error(errMsg, { cause })
  }

  if (res.status >= 400 && res.status <= 499 && errData.message) {
    throw new UserFacingApiError(errData.message)
  }

  throw new HttpError({ statusCode: res.status, message: errMsg })
}

function emitSocketProgress<M extends Meta, B extends Body>(
  uploader: { uppy: Uppy<M, B> },
  progressData: {
    progress: string // pre-formatted percentage number as a string
    bytesTotal: number
    bytesUploaded: number
  },
  file: UppyFile<M, B>,
): void {

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Inspect the thrown error's status (parse from message) and the cause to see what the body actually was
2. Fix the companionUrl / proxy configuration so JSON responses (and errors) come from Companion itself
3. Check the Network tab to see the raw response body for the failing request
4. If a proxy intercepts errors, configure it to pass through upstream JSON error responses

Example fix

// before
// companionUrl misrouted; proxy returns HTML 502 page
const data = await companionRequestClient.get('/url') // throws generic Error

// after
new Url(uppy, { companionUrl: 'https://companion.example.com' })
// nginx: proxy_pass http://companion:3020; and avoid custom error_page interception

null

null

try {
  await client.get('/url')
} catch (err) {
  const status = Number(/status: (\d+)/.exec(err.message)?.[1])
  if (status >= 500) { /* gateway issue, retry later */ }
}

When it happens

Trigger: A RequestClient request returns a non-OK status AND res.json() throws (body is HTML/plain text) — typical for 502/504 gateway errors from nginx, a Companion route served behind a misconfigured proxy, or hitting a non-Companion URL that returns an error page.

Common situations: companionUrl points to a wrong path; reverse proxy returns HTML error pages (502 Bad Gateway, Cloudflare challenge); Companion crashed and something else answers; rate-limit pages from CDNs.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• File data is missing for file ${options.file.id}
• Missing S3 object key for aborting upload
• Missing S3 object key for resuming upload
• Missing S3 object key for uploading part
• Missing S3 object key for completing multipart upload

AI-assisted analysis of transloadit/uppy@5d4dedd02a (2026-08-28). Data as JSON: /api/errors/13a005201aa8323d. Report an issue: GitHub.