Deleting

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 pathawait bucket.del(["a.png", "b.png", "c.png"])        // an array of pathsawait bucket.del({ prefix: "tmp/" })                 // everything under a prefix

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

// one pathbucket.Delete(ctx, "avatars/me.png")// a slice of pathsbucket.DeleteMany(ctx, []string{"a.png", "b.png", "c.png"})// everything under a prefixbucket.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.Errorif 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.

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

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

bucket.DeleteAll(ctx)

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.

Aborting one upload#

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

from upstash_blob import MultipartUploadbucket.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.

Error codes#

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