delete
Remove an object - a single key resolving to void, or an array returning a structured result that never throws on partial failure.
files.delete(key) · files.delete(keys)
Pass a single key to remove one object, or an array to remove many in one call. The two forms differ in how failures surface.
One key removes a single object and resolves to void. No-op friendly: a missing key resolves successfully on providers that treat delete as idempotent, and throws FilesError with code: "NotFound" on ones that don’t.
await files.delete("avatars/abc.png");
Delete only the expected generation
The single-key form accepts an exact ETag predicate. The provider removes the object only if that generation is still current; unsupported adapters and stale predicates fail closed.
await files.delete("avatars/abc.png", {
condition: { etag: current.etag! },
});
Conditional delete has no array form. See Conditional operations for capability and retry semantics.
Many keys
Returns a structured result instead of throwing on partial failure. Adapters with a native bulk primitive (S3 DeleteObjects, Azure’s Blob Batch API, Supabase, UploadThing, the R2 Workers binding) delete in a single request — the S3 path and the R2 binding chunk into batches of 1000 and Azure into batches of 256, the respective provider limits — while the rest fan out to single deletes with bounded concurrency (FTP and SFTP reuse one connection for the sequence). An instance with a plugin that wraps operations always fans out, so the plugin sees each key. Like the single form, it honors the client’s prefix and is no-op friendly on providers that treat a missing key as success.
const result = await files.delete(
["avatars/a.png", "avatars/b.png", "avatars/c.png"],
{ concurrency: 8, stopOnError: false }
);
result.results; // string[] — keys removed, in the order supplied
result.errors; // undefined when every key succeeded
The array form always resolves to an object of this shape:
type DeleteManyResult = {
results: string[];
errors?: Array<{ key: string; error: FilesError }>;
};
With the default stopOnError: false, every key is attempted and per-key failures are collected in errors. With stopOnError: true, keys are deleted one at a time (skipping the native batch, which can’t stop partway) and the call stops at the first failure, returning the keys deleted so far plus that error. Invalid keys (empty, or containing null bytes) are reported in errors rather than thrown. When a native bulk provider only reports that the whole request failed, the provider error is mapped onto each affected key.
Options (array form)
concurrency?number
How many per-key operations run in parallel. Defaults to `8`. Ignored when `stopOnError` is set — that path runs sequentially. A bulk `delete` on an adapter with a native batch primitive ignores it too: S3 and the S3-compatible adapters (on the `aws-sdk` client), Azure, Supabase, UploadThing, and the R2 Workers binding batch the keys into as few requests as the provider allows, and FTP / SFTP delete sequentially over one connection. With a wrapping plugin installed, or without a native batch, the SDK fans out to per-key `delete()` calls under this concurrency.
numberstopOnError?boolean
When `true`, stop at the first failure and return immediately with the results gathered so far plus that error. When `false` (default), process every item and collect per-key failures in `errors`. It always runs the per-key calls one at a time, in input order — a bulk `delete` included, which skips the adapter's native batch (a batch request can't stop partway) — so it behaves the same with or without plugins.
boolean