Deleting - Upstash Documentation

This page covers deleting one path, a list of paths, or everything under a prefix, and the calls that clean up multipart uploads that were never completed.

await bucket.del("avatars/me.png")                   // one path
await bucket.del(["a.png", "b.png", "c.png"])        // an array of paths
await bucket.del({ prefix: "tmp/" })                 // everything under a prefix

bucket.delete("avatars/me.png")                  # one path
bucket.delete(["a.png", "b.png", "c.png"])       # a list of paths
bucket.delete(prefix="tmp/")                      # everything under a prefix

// one path
bucket.Delete(ctx, "avatars/me.png")
// a slice of paths
bucket.DeleteMany(ctx, []string{"a.png", "b.png", "c.png"})
// everything under a prefix
bucket.DeletePrefix(ctx, "tmp/")

All three shapes return nothing and treat “already gone” as success. They differ in how many requests they make and what they throw when storage refuses part of the work. Method signatures and the target type: TypeScript, Python, Go. A target that is none of the three shapes is refused with invalid_input. In Python that is passing both or neither of paths and prefix=; any other iterable, a dict included, is read as a list of paths. Go has a method per shape, so there is no target to get wrong. A path with a . or .. segment is rejected before any request is sent; see Paths. The upload handler also deletes on its own: a throw out of the completion callback, or a cancel from the browser, removes the object that upload wrote. See Recording the upload.

One path

await bucket.del("drafts/9f3c.txt")
await bucket.del("drafts/9f3c.txt")  // still no throw

bucket.delete("drafts/9f3c.txt")
bucket.delete("drafts/9f3c.txt")  # still no raise

bucket.Delete(ctx, "drafts/9f3c.txt")
bucket.Delete(ctx, "drafts/9f3c.txt") // still nil

One DELETE request. A 404 counts as success, so a delete is safe to run from a retried job or an at-least-once queue consumer. Any other failure throws; see Errors. A delete never says whether anything was there. To find out, call exists first.

A list of paths

try {
  await bucket.del(paths)
} catch (e) {
  if (BlobError.is(e) && e.code === "partial_delete") {
    await requeue(e.failed ?? [])  // the paths still in the bucket, verified one by one
    return
  }
  throw e
}

try:
    bucket.delete(paths)
except BlobError as e:
    if e.code != "partial_delete":
        raise
    requeue(e.failed or [])  # the paths still in the bucket, verified one by one

err := bucket.DeleteMany(ctx, paths)
var be *blob.Error
if errors.As(err, &be) && be.Code == blob.CodePartialDelete {
	// the paths still in the bucket, verified one by one
	return requeue(be.Failed)
}
if err != nil {
	return err
}

Sent as batch deletes in chunks of 1000 paths, so a 5000-path list is five requests. In TypeScript a bad path fails the chunk it is in, and earlier chunks have already run. Python and Go check every path before the first request, so nothing is deleted. When storage reports keys as failed, the SDK re-checks each one and keeps only the paths still there. If any survive, the delete throws partial_delete with them as its failed paths. Everything not in that list was deleted. To recover, retry with those paths.

A prefix

await bucket.del({ prefix: "users/7/tmp/" })

bucket.delete(prefix="users/7/tmp/")

bucket.DeletePrefix(ctx, "users/7/tmp/")

Pages through list at 1000 objects per page and batch-deletes each page as it goes. A prefix with 100,000 objects is 100 list requests and 100 batch deletes, run one after another. It is not atomic; objects written under the prefix while it runs may or may not be caught. Failures work as for a list. Survivors from every page are collected and thrown as partial_delete.

An empty prefix would match every object in the bucket, so it is refused with invalid_input. This protects against an unset variable or an empty form field. To wipe the bucket on purpose, say so with the all flag, or in Go with DeleteAll:

await bucket.del({ prefix: "", all: true })

bucket.delete(prefix="", all=True)

bucket.DeleteAll(ctx)

The all flag is only consulted for the empty prefix.

`move` leaves a copy on failure

try {
  await bucket.move("tmp/9f3c", "avatars/7.png")
} catch (e) {
  if (BlobError.is(e) && e.code === "move_left_a_copy") {
    // avatars/7.png exists and is correct. tmp/9f3c is also still there.
    await bucket.del("tmp/9f3c")  // retry the source delete, not the move
    return
  }
  throw e
}

try:
    bucket.move("tmp/9f3c", "avatars/7.png")
except BlobError as e:
    if e.code != "move_left_a_copy":
        raise
    # avatars/7.png exists and is correct. tmp/9f3c is also still there.
    bucket.delete("tmp/9f3c")  # retry the source delete, not the move

_, err := bucket.Move(ctx, "tmp/9f3c", "avatars/7.png", nil)
if blob.HasCode(err, blob.CodeMoveLeftACopy) {
	// avatars/7.png exists and is correct. tmp/9f3c is also still there.
	// retry the source delete, not the move
	return bucket.Delete(ctx, "tmp/9f3c")
}
if err != nil {
	return err
}

move is a copy followed by a delete, because storage has no rename. If the copy fails, nothing changed and you get the copy’s error. If the copy succeeds and the delete fails, move throws move_left_a_copy and keeps the destination, so you have two objects rather than none. The original error is on the error’s cause.

Incomplete multipart uploads

A multipart upload becomes an object only when it is completed. Until then its parts are billed storage that list cannot see, and the bucket cannot be deleted while one exists. A browser tab closed mid-upload leaves exactly this behind. put and a browser cancel abort their own uploads on failure. Anything else needs a sweep. The cron that runs it is on Abandoned uploads; the calls it uses are below. Signatures: TypeScript, Python, Go.

Listing incomplete uploads

const uploads = await bucket.listMultipartUploads({ prefix: "uploads/" })
// [{ path: 'uploads/big.mp4', uploadId: 'ABC...', initiatedAt: Date }, ...]

uploads = bucket.list_multipart_uploads(prefix="uploads/")
# [MultipartUpload(path='uploads/big.mp4', upload_id='ABC...', initiated_at=datetime(...)), ...]

uploads, err := bucket.ListMultipartUploads(ctx, "uploads/")
// [{Path: "uploads/big.mp4", UploadID: "ABC...", InitiatedAt: time.Time}, ...]

Returns every upload started and neither completed nor aborted, paging internally until it has them all. The prefix is optional.

Field	Meaning
Path	The key the upload was started for. Nothing is stored there yet.
Upload id	Storage’s id for the upload, needed to abort it.
Initiated at	When it was started. What “stale” is measured against.

Aborting one upload

await bucket.abortMultipartUpload({ path: "uploads/big.mp4", uploadId: "ABC..." })

from upstash_blob import MultipartUpload

bucket.abort_multipart_upload(MultipartUpload(path="uploads/big.mp4", upload_id="ABC...", initiated_at=None))

bucket.AbortMultipartUpload(ctx, blob.MultipartUpload{
	Path:     "uploads/big.mp4",
	UploadID: "ABC...",
})

Throws the upload away with every part that landed for it. An upload that is already gone counts as success. An empty upload id is refused with invalid_input. The completion callback receives the multipart upload id for exactly this pair. Store it with your row and you can abort a specific upload later without listing the bucket. It is not set for a single PUT.

Aborting stale uploads

const aborted = await bucket.abortStaleMultipartUploads({
  olderThan: "1d",
  prefix: "uploads/",
})
// [{ path, uploadId, initiatedAt }, ...]

aborted = bucket.abort_stale_multipart_uploads(older_than="1d", prefix="uploads/")
# [MultipartUpload(path, upload_id, initiated_at), ...]

aborted, err := bucket.AbortStaleMultipartUploads(ctx, 24*time.Hour, "uploads/")
// [{Path, UploadID, InitiatedAt}, ...]

List plus abort in one call, meant for a cron. The older-than window is required, a Duration. In Go it is a time.Duration, and zero aborts every incomplete upload under the prefix. Only uploads started longer ago than that are touched, so a window longer than your slowest upload never aborts one still running. A day is a reasonable default.

An abandoned upload under the multipart threshold is not a multipart upload. It is an ordinary stored object that list can see, and none of the calls above can find it. See Abandoned uploads.

Error codes

Code	Raised by
`partial_delete`	A list or prefix delete where objects survived. The error lists them.
`move_left_a_copy`	`move`, when the source delete failed.
`invalid_input`	A bad delete target, an empty prefix without the all flag, an empty upload id.

A delete never raises not_found. Statuses and extra fields are on Errors.

​One path

​A list of paths

​A prefix

​move leaves a copy on failure

​Incomplete multipart uploads

​Listing incomplete uploads

​Aborting one upload

​Aborting stale uploads

​Error codes

One path

A list of paths

A prefix

`move` leaves a copy on failure

Incomplete multipart uploads

Listing incomplete uploads

Aborting one upload

Aborting stale uploads

Error codes