transloadit/uppy · error

Failed to download file

Error message

Failed to download file

What it means

This is Companion's GET download controller catching any error from startDownUpload (the pipeline that streams a provider file to the client or an uploader). When the failure isn't mapped by respondWithError, Companion responds 500 with 'Failed to download file'.

Source

Thrown at packages/@uppy/companion/src/server/controllers/get.ts:35

  }

  const getSize = async () =>
    provider.size({ id, providerUserSession, query: req.query })

  const download = () =>
    provider.download({
      id,
      providerUserSession,
      query: req.query,
      companion: req.companion,
    })

  try {
    await startDownUpload({ req, res, getSize, download })
  } catch (err) {
    logger.error(err, 'controller.get.error', req.id)
    if (respondWithError(err, res)) return
    res.status(500).json({ message: 'Failed to download file' })
  }
}

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Check Companion logs (logger.error output with req.id) for the underlying cause
2. Retry the download — many causes are transient provider/network failures
3. If token expiry recurs, reduce download window or refresh provider tokens more aggressively

const res = await fetch(url)
if (res.status === 500 && (await res.json()).message === 'Failed to download file') {
  await new Promise((r) => setTimeout(r, 1000))
  return retryFetch(url, retries - 1)
}

When it happens

Trigger: GET /companion/:provider/get/:id where the provider download fails unexpectedly: expired access token mid-download, provider 5xx, socket abort, or an error shape not covered by respondWithError's mapping.

Common situations: Long downloads where the provider OAuth token expires, transient provider outages, network interruption between Companion and the provider, or bugs in custom provider implementations returning non-standard errors.

Related errors

• File data is missing for file ${options.file.id}
• Missing S3 object key for completing multipart upload
• [s3mini] fileType must be a string
• [s3mini] uploadId must be a non-empty string
• Missing token payload for provider ${providerName}

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