Timeouts
A per-attempt timeout that aborts the call when it fires — it ends the operation rather than triggering another attempt.
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: r2({ 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 makes up to n + 1 attempts, so it can run for as long as timeout × (n + 1) plus the backoff waits in between. Budget for the whole call accordingly, or bound it end-to-end with a signal you abort yourself.
Bulk calls
The array forms (upload([…]), delete([…]), …) give each per-key call its own timeout, and an item that times out lands in the result’s errors rather than rejecting the call. A native bulk delete goes out in slices of up to 1000 keys while a constructor timeout is set, each slice with its own timeout. The first slice that times out ends the delete, since a request it had in flight may still be running: that slice’s keys and those of the slices not yet sent land in errors, while the keys earlier slices deleted stay in results. The adapter gets the slice’s abort signal: FTP and SFTP stop before their next key, and S3 and Azure cancel the batch request in flight. A provider that already received a request may still carry it out, so some keys of the timed-out slice may still get deleted after the call returns.
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.