Timeouts

timeout caps how long a single attempt may run, in milliseconds. When it fires, the in-flight call is aborted and rejects with a Provider FilesError (Operation timed out after Nms, with aborted: true). A timeout is not retried — it ends the call rather than triggering another attempt. There is no timeout by default; set one on the constructor or per call, and pass 0 (or a negative value) to disable it.

// Constructor default, overridden per call.
const files = new Files({
  adapter: s3({ bucket: "uploads" }),
  timeout: 10_000,
});

await files.head("avatars/abc.png", { timeout: 2_000 }); // tighter for one read
await files.download("big.zip", { timeout: 0 }); // disabled for a large object

A per-call value always wins over the constructor default for that operation.

Per attempt, not per call

The timeout applies to each attempt, not to the call as a whole. Since a timeout isn't itself retryable, this only matters across retries triggered by other (provider) failures: if attempt 1 fails with a retryable provider error, attempt 2 starts with a fresh timeout. A call that retries up to n times can therefore run for as long as timeout × n plus the backoff waits in between. Budget for the whole call accordingly, or bound it end-to-end with a signal you abort yourself.

Interaction with adapter timeouts

Some adapters apply their own download timeout (Vercel Blob, UploadThing). When both are in play the two abort signals are merged, so whichever fires first wins — your timeout can tighten the deadline but never loosen the adapter's.

See Retries for what counts as retryable, and Cancellation for caller-driven aborts, which share the same aborted failure shape.