Errors

try {  return await bucket.info(path)} catch (e) {  if (BlobError.is(e) && e.code === "not_found") return null  throw e}

try:    return bucket.info(path)except BlobError as e:    if e.code == "not_found":        return None    raise

info, err := bucket.Info(ctx, path)if blob.HasCode(err, blob.CodeNotFound) {	return nil, nil}return info, err

Every failure the SDK reports is a BlobError. Most bad options and arguments are a TypeError instead, a ValueError in Python, and in Go an error returned where the option is written; see TypeScript, Python, Go. It carries a code from a fixed list, a status, and a message you can show to a user. The same codes are used by every server SDK, in the browser, and inside the React hooks, so an error raised on your server reaches the browser with its code intact.

Catching it and reading its fields: TypeScript, Python, Go.

The codes#

The status is what an upload route answers with.

Bad option values are not in this list. An unparseable '5mbit', a missing token, a route with no before-upload callback: those throw where the option is written, at startup, not as a BlobError per request. What they throw in each SDK: TypeScript, Python, Go.

Extra fields#

Some codes carry extra details. Their names and types in each SDK: TypeScript, Python, Go.

Messages#

new BlobError("not_found").message                         // 'Not found'new BlobError("forbidden", "not your thread").message       // 'Not your thread'new BlobError("too_large", "cat.png is 3.1 MB, over the 2 MB limit").message// 'cat.png is 3.1 MB, over the 2 MB limit'

BlobError("not_found").message                    # 'Not found'BlobError("forbidden", "not your thread").message  # 'Not your thread'BlobError("too_large", "cat.png is 3.1 MB, over the 2 MB limit").message# 'cat.png is 3.1 MB, over the 2 MB limit'

blob.NewError(blob.CodeNotFound, blob.ErrorOptions{}).Message// "Not found"blob.NewError(blob.CodeForbidden, blob.ErrorOptions{	Message: "not your thread",}).Message// "Not your thread"blob.NewError(blob.CodeTooLarge, blob.ErrorOptions{	Message: "cat.png is 3.1 MB, over the 2 MB limit",}).Message// "cat.png is 3.1 MB, over the 2 MB limit"

Messages are sentence-cased, so an app can print the message directly. A message that opens with an identifier, like a MIME type or a file name, keeps that identifier’s case.

A message never carries a credential, a token, or an internal path. Every message is assembled from a code, a caller-supplied string, an HTTP status, or the reason Upstash’s signing service gave. A suspended or read-only bucket is the exception: that notice is meant for you, not your users, so it is on the error’s cause instead.

Hints fold into the message#

new BlobError("length_required").message// 'Length required (pass { size } or { maxSize } so the length is known before the first byte)'

BlobError("length_required").message# 'Length required (pass size= or max_size= so the length is known before the first byte)'

blob.NewError(blob.CodeLengthRequired, blob.ErrorOptions{}).Message// "Length required (pass Size or MaxSize so the length is known// before the first byte)"

A hint is appended to the message in parentheses, so printing the message alone is enough. The hint is still there separately if you want to lay it out yourself. A message that already contains its hint is not doubled.

signature_mismatch and length_required have a built-in hint. Its text in each SDK: TypeScript, Python, Go.

Errors in the browser#

"use client"import type { BlobError } from "@upstash/blob/react"import { useUpload } from "@/lib/upload-hooks"export function Picker() {  const { start, upload, accept } = useUpload()  return (    <>      <input        type="file"        accept={accept}        onChange={(e) => start({ file: e.target.files?.[0] })}      />      {upload?.status === "error" && <p role="alert">{describe(upload.error)}</p>}    </>  )}function describe(error: BlobError): string {  switch (error.code) {    case "unauthorized":      return "Your session expired. Sign in and try again."    case "rate_limited":      return `Too many uploads. Try again in ${error.retryAfter ?? 30}s.`    case "not_ready":      return "Storage is warming up. Try again in a moment."    default:      // too_large, content_type_not_allowed and the rest already read as a sentence.      return error.message  }}

An upload route, in any server SDK, answers every refusal with the error’s own code and status, and the browser rebuilds it. error.code inside a hook is the code your server raised, not a status number you have to decode.

What reaches the browser, in order#

A route runs its error callback first. If it returns a response, that is the answer; if it returns a BlobError, the answer is that error’s JSON at its own status. Otherwise the throw falls through three cases:

1. A BlobError is answered as itself, at its own status, with its hint, failed paths, etag, size and retry-after when they are set.
2. An app error carrying a status between 400 and 599 is mapped through the table below. This is how an auth check that throws its own 401 reaches the browser as unauthorized.
3. Anything else is treated as your bug and rethrown, so your framework logs it with its stack rather than masking it as a generic 500.

In Go the status in case 2 comes from a StatusCode() int method on the error, and case 3 has nothing to rethrow to: the handler logs the error on its Logger and answers a 500 with no detail. See Refusing.

Any other status becomes request_failed, keeping the status it arrived with.

A throw out of the completion callback also deletes the completed object before the error is answered. See Recording the upload.

What storage errors map to#

Storage is Cloudflare R2. Its errors are normalized before they leave the SDK, first matching wins.

For that last row the status is passed through, except that a 5xx becomes 502, since the failure is upstream of your app rather than in it.

Errors the browser raises on its own#

Some failures never reach your route, so the browser names them itself.

A PUT that fails with no status and no bytes sent was refused by the browser before it went out, and the reason is never visible to script because it is the preflight that failed:

the browser blocked the request before sending any bytes, which is almost always CORS:the bucket has to allow PUT and the signed headers from this origin

Buckets allow every origin by default, so this only shows up on a bucket whose CORS policy was narrowed.

A 403 on a freshly minted presign becomes signature_mismatch. A 401 or 403 on an older URL is read as an expired signature and the browser asks the route for a new one instead. See Retries.

Exhausted retries become request_failed, carrying the attempt count and the last status, hinted with what to do next:

Upload failed after 8 attempts (last status 500) (the parts that landed are kept:task.retry(), or pick the same file again)

A canceled upload rejects with an AbortError, not a BlobError. The record’s status is canceled and it carries no error at all, so a cancel never renders as a failure.

const record = start({ file })record?.cancel()          // status becomes 'canceled', error stays undefined

Platform body limits#

const { start, upload } = useServerUpload("/api/avatar")if (upload?.status === "error" && upload.error.code === "too_large") {  // Either your own maxSize or the platform's body cap. e.hint says which.}

This applies to useServerUpload and any route of your own that the bytes pass through. It does not apply to direct browser uploads.

Vercel caps a serverless request body at 4.5MB, AWS Lambda at 6MB, and Cloudflare at 100MB on the free plan. A file over that cap is refused with a 413 that never reached your route, so it carries no code of its own. The SDK turns it into too_large and attaches the cap as a hint:

Too large (Vercel caps a serverless request body at 4.5MB, AWS Lambda at 6MB,Cloudflare at 100MB on the free plan)

Keep a proxied route’s own max size under the platform’s cap, so the refusal comes from your code with your wording. A file bigger than the cap needs a direct browser upload instead.

Credential errors#

try {  await bucket.put("u/7/report.pdf", body)} catch (e) {  if (BlobError.is(e) && e.code === "mint_backoff") {    return retryAfterSeconds(e.retryAfter ?? 10)  }  throw e}

try:    bucket.put("u/7/report.pdf", body)except BlobError as e:    if e.code == "mint_backoff":        return retry_after_seconds(e.retry_after or 10)    raise

_, err := bucket.Put(ctx, "u/7/report.pdf", body, nil)var be *blob.Errorif errors.As(err, &be) && be.Code == blob.CodeMintBackoff {	return retryAfter(be.RetryAfter)}return err

Three codes come from the credential service rather than from storage or from your code.

The SDK waits out short backoffs itself. mint_backoff is a pause too long for one request to wait through, handed back to you instead of holding a serverless invocation open.

Credentials are short-lived and re-minted before they expire. One that expires mid-request is handled inside the SDK, so only a second refusal surfaces. See How signing works.