What causes "Failed to download file" in transloadit/uppy?

Check Companion logs (logger.error output with req.id) for the underlying cause

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'.

Solutions

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

Defensive patterns

Strategy: retry

Try / catch

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)
}

Prevention

Correlate failures with req.id in Companion logs to find root cause
Implement client-side retry with backoff for downloads
Monitor provider token expiry and provider status pages

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

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

Appendix: 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)