Errors

import { BlobError, Bucket } from "@upstash/blob"const bucket = Bucket.fromEnv()export async function avatar(path: string) {  try {    return await bucket.info(path)  } catch (e) {    if (BlobError.is(e) && e.code === "not_found") return null    throw e  }}

Everything the SDK throws is a BlobError. It carries a code from a fixed list, a status, and a message you can show to a user. The same class and codes are used on the server, in the browser, and inside the React hooks.

BlobError is exported from all three entrypoints: @upstash/blob, @upstash/blob/browser and @upstash/blob/react.

Use BlobError.is(), not instanceof#

if (BlobError.is(e)) {  e.code    // BlobErrorCode  e.status  // number  e.message // string}

is() is a type guard, so the fields are typed after it.

The codes#

e.status is what an upload route answers with.

Bad option values are not in this list. An unparseable '5mib', a missing token, a route with no onBeforeUpload: those throw a TypeError where the option is written, not a BlobError per request.

Extra fields#

try {  await bucket.del(["a.png", "b.png", "c.png"])} catch (e) {  if (!BlobError.is(e)) throw e  if (e.code === "partial_delete") await queueForRetry(e.failed ?? [])  if (e.code === "rate_limited") await sleep((e.retryAfter ?? 1) * 1000)}

Some codes carry extra fields.

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'

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

e.message never carries a credential, a token, or an internal path. Every message is assembled from a code, a caller-supplied string, or an HTTP status.

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)'

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

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 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 onError 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 hint, failed, etag, size and retryAfter 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.

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

A throw out of onUploadComplete also deletes the completed object before the error is answered. See onUploadComplete.

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.

A 413 from the platform never reached your route, so it carries no code of its own. The SDK turns it into too_large and attaches the limits 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 maxSize 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}

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.