Postconditions: what we check

• put · blob-put-no-try-catch

  error
  WhenMissing BLOB_READ_WRITE_TOKEN (BlobAccessError), content-type not allowed (BlobContentTypeNotAllowedError), storage quota exceeded (BlobStoreLimitReachedError), network failure, or Vercel API unavailable (BlobUnknownError).
  ThrowsBlobAccessError, BlobContentTypeNotAllowedError, BlobStoreLimitReachedError, or BlobUnknownError. All extend BlobError which extends Error.
  Required handlingCaller MUST wrap put() in try-catch. Missing BLOB_READ_WRITE_TOKEN causes immediate BlobAccessError (common in deployments that forgot to set the env var). Storage quota errors are hard to predict and will crash file upload endpoints if unhandled. Minimum handling: try { const blob = await put('file.pdf', content, { access: 'public' }); return blob.url; } catch (err) { if (err instanceof BlobAccessError) { throw new Error('Blob storage not configured'); } throw err; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• del · blob-del-no-try-catch

  error
  WhenMissing auth token, network failure, or Vercel API unavailable.
  ThrowsBlobAccessError or BlobUnknownError.
  Required handlingCaller MUST wrap del() in try-catch. Failed deletions leave orphaned blobs that incur storage costs.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• list · blob-list-no-try-catch

  error
  WhenMissing auth token or network failure.
  ThrowsBlobAccessError or BlobUnknownError.
  Required handlingCaller MUST wrap list() in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• head · blob-head-no-try-catch

  error
  Whenhead() THROWS BlobNotFoundError when the blob does not exist — it does NOT return null.
  ThrowsBlobNotFoundError, BlobAccessError, BlobStoreNotFoundError, or BlobUnknownError.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• head · blob-head-access-error

  error
  Whenhead() throws BlobAccessError when BLOB_READ_WRITE_TOKEN is missing, invalid, or the token does not have access to the requested store.
  ThrowsBlobAccessError or BlobStoreNotFoundError.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• copy · blob-copy-no-try-catch

  error
  Whencopy() throws on any error: BlobAccessError (auth failure), BlobNotFoundError (source blob doesn't exist), BlobUnknownError (network failure), or BlobPreconditionFailedError (ETag mismatch when ifMatch is used).
  ThrowsBlobAccessError, BlobNotFoundError, BlobUnknownError, or BlobPreconditionFailedError.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• copy · blob-copy-source-not-found

  error
  Whencopy() throws BlobNotFoundError when the source blob (fromUrlOrPathname) does not exist.
  ThrowsBlobNotFoundError.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• get · blob-get-null-not-checked

  error
  Whenget() returns null when the blob is not found (HTTP 404) — it does NOT throw.
  ReturnsGetBlobResult | null (null when blob not found — callers must null-check before accessing stream or blob).
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• get · blob-get-no-try-catch

  error
  Whenget() throws BlobAccessError (auth failure), BlobServiceRateLimited (HTTP 429, retryAfter seconds available on error), or BlobServiceNotAvailable (Vercel API down).
  ThrowsBlobAccessError, BlobServiceRateLimited, or BlobServiceNotAvailable.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• handleUpload · blob-handle-upload-missing-auth-check

  error
  WhenonBeforeGenerateToken must authenticate the user before returning token options.
  ThrowsBlobAccessError or any error thrown from onBeforeGenerateToken/onUploadCompleted callbacks.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• handleUpload · blob-handle-upload-no-try-catch

  error
  WhenhandleUpload() itself throws BlobAccessError when BLOB_READ_WRITE_TOKEN is missing or invalid.
  ThrowsBlobAccessError when BLOB_READ_WRITE_TOKEN is missing or invalid, or re-throws from callbacks.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• createMultipartUpload · blob-create-multipart-no-try-catch

  error
  WhencreateMultipartUpload() throws BlobAccessError (auth failure), BlobServiceRateLimited (rate limit with retryAfter), or BlobUnknownError (network failure).
  ThrowsBlobAccessError, BlobServiceRateLimited, or BlobUnknownError.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• uploadPart · blob-upload-part-no-try-catch

  error
  WhenuploadPart() throws BlobAccessError, BlobFileTooLargeError, BlobUnknownError, or BlobServiceRateLimited.
  ThrowsBlobAccessError, BlobFileTooLargeError, BlobUnknownError, or BlobServiceRateLimited.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• uploadPart · blob-upload-part-minimum-size

  warning
  WhenEach part (except the last) must be at least 5MB.
  ThrowsBlobFileTooLargeError when a part is smaller than 5MB (except the last part).
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• completeMultipartUpload · blob-complete-multipart-no-try-catch

  error
  WhencompleteMultipartUpload() throws BlobAccessError (auth failure), BlobUnknownError (network failure or invalid parts), or BlobServiceNotAvailable.
  ThrowsBlobAccessError, BlobUnknownError, or BlobServiceNotAvailable.
  Required handlingCaller MUST handle this condition appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• upload · blob-upload-missing-handle-url

  error
  WhenhandleUploadUrl option is not provided to upload(). This is a required parameter — upload() cannot work without a server route to fetch a client token from.
  ThrowsBlobError: client/`upload` requires the 'handleUploadUrl' parameter
  Required handlingCaller MUST always provide handleUploadUrl. This error throws synchronously during options validation before any network request is made — it is a programming error, not a runtime failure. Add a validation check at component initialization time.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• upload · blob-upload-token-fetch-failed

  error
  WhenThe handleUploadUrl server route returns a non-2xx response (auth failure, server error, route not found), or the response body is not valid JSON containing clientToken. Common causes: missing authentication middleware on the handleUpload route, route misconfiguration, or server returning HTML error page instead of JSON.
  ThrowsBlobError: Failed to retrieve the client token
  Required handlingCaller MUST wrap upload() in try-catch. The token fetch is the first network request in the upload flow — if it fails, the upload never starts. Common mistake: the handleUpload route is protected by auth middleware that redirects unauthenticated requests to /login (HTML, not JSON), causing this error. Ensure the route returns JSON even on auth failure.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• upload · blob-upload-server-only-options-used

  error
  WhenCaller passes addRandomSuffix, cacheControlMaxAge, allowOverwrite, or ifMatch to upload(). These options are only valid for server-side put(). They must be configured in onBeforeGenerateToken on the server side, not in the client-side upload() call.
  ThrowsBlobError: client/`upload` doesn't allow `addRandomSuffix`, `cacheControlMaxAge`, `allowOverwrite` or `ifMatch`. Configure these options at the server side when generating client tokens.
  Required handlingMove storage configuration options to the server-side onBeforeGenerateToken callback in your handleUpload route. Do not pass them to upload() on the client. The client token embeds these settings from the server at token-generation time.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• upload · blob-upload-client-token-expired

  warning
  WhenThe client token has expired (default TTL: 1 hour from generateClientTokenFromReadWriteToken call). This happens when: the user keeps the file picker open for more than an hour before clicking upload, or when tokens are pre-generated and cached longer than their TTL.
  ThrowsBlobClientTokenExpiredError: Client token has expired.
  Required handlingCaller MUST catch BlobClientTokenExpiredError separately from other errors and prompt the user to retry (which will generate a fresh token). Do not treat expired token as a permanent failure. The BlobClientTokenExpiredError class is exported from '@vercel/blob/client' for instanceof checks.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][5]
• generateClientTokenFromReadWriteToken · blob-generate-client-token-browser-env

  error
  WhengenerateClientTokenFromReadWriteToken() is called from a browser environment (where typeof window !== 'undefined'). This function requires server-side crypto to sign the token payload and must never be called client-side as it would expose the BLOB_READ_WRITE_TOKEN to users.
  ThrowsBlobError: "generateClientTokenFromReadWriteToken" must be called from a server environment
  Required handlingNever call generateClientTokenFromReadWriteToken() in client-side code (React components, browser scripts, client-side Next.js pages). It must only be called in server-side code: API routes, Server Actions, getServerSideProps, or route handlers in Next.js App Router. The read-write token must never be exposed to the browser.
  costhighin prodimmediate exceptionusers seeauthentication failurevisibilityvisible
  Sources[3][4]
• generateClientTokenFromReadWriteToken · blob-generate-client-token-invalid-token

  error
  WhenThe BLOB_READ_WRITE_TOKEN is missing, malformed (doesn't contain the expected storeId segment after the 4th underscore), or the token option is passed but invalid. The token format is: vercel_blob_rw_<storeId>_<secret>.
  ThrowsBlobError: Invalid `token` parameter (if token option given) or Invalid `BLOB_READ_WRITE_TOKEN`
  Required handlingCaller MUST wrap generateClientTokenFromReadWriteToken() in try-catch. This commonly fails in development when BLOB_READ_WRITE_TOKEN is not pulled via `vercel env pull`. Validate the environment variable is set at application startup. When this throws inside handleUpload(), the entire upload route fails with 500.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][4]
• generateClientTokenFromReadWriteToken · blob-generate-client-token-conflicting-options

  warning
  WhenBoth ifMatch and allowOverwrite: false are specified in the token options. These options are contradictory: ifMatch implies a conditional overwrite (allowOverwrite must be true), but allowOverwrite: false forbids overwrites entirely.
  ThrowsBlobError: ifMatch and allowOverwrite: false are contradictory. ifMatch is used for conditional overwrites, which requires allowOverwrite to be true.
  Required handlingWhen using ifMatch for optimistic concurrency control, either omit allowOverwrite (the SDK will auto-set it to true) or explicitly pass allowOverwrite: true. Do not combine ifMatch with allowOverwrite: false.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][4]
• createMultipartUploader · blob-create-multipart-uploader-no-try-catch

  error
  WhencreateMultipartUploader() throws BlobAccessError (auth failure), BlobServiceRateLimited (rate limit), BlobServiceNotAvailable (network failure / fetch failed), or BlobUnknownError. The initial call creates the upload session — if it fails, no session is created and no cleanup is needed.
  ThrowsBlobAccessError, BlobServiceRateLimited, BlobServiceNotAvailable, or BlobUnknownError.
  Required handlingCaller MUST wrap the createMultipartUploader() call in try-catch. The returned uploader object's uploadPart() and complete() methods also throw and must each be individually caught. A failed uploadPart() does not automatically abort the session — the session remains open until complete() is called or it expires server-side.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][7]
• createMultipartUploader · blob-create-multipart-uploader-plain-object-body

  error
  Whenuploader.uploadPart() is called with a plain JavaScript object as the body (e.g., { content: 'data' }). The body must be a string, Buffer, ReadableStream, File, or Blob. This is a runtime validation error that throws synchronously.
  ThrowsBlobError: Body must be a string, buffer or stream. You sent a plain JavaScript object, double check what you're trying to upload.
  Required handlingEnsure the body passed to uploader.uploadPart() is a proper binary or text type. Common mistake: passing a JS object that represents file metadata instead of the actual file content. Convert to Buffer, Blob, or ReadableStream before uploading.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][7]
• createFolder · blob-create-folder-no-try-catch

  error
  WhencreateFolder() throws BlobAccessError (auth failure / missing token), BlobStoreSuspendedError (store has been suspended), BlobStoreNotFoundError (store in token references deleted store), BlobServiceRateLimited, BlobServiceNotAvailable (network failure), or BlobUnknownError.
  ThrowsBlobAccessError, BlobStoreSuspendedError, BlobStoreNotFoundError, BlobServiceRateLimited, BlobServiceNotAvailable, or BlobUnknownError.
  Required handlingCaller MUST wrap createFolder() in try-catch. Although folder creation is typically a one-time setup operation, failures in file browser features must be handled to surface errors to users rather than silently creating an incomplete folder hierarchy. The returned url should be stored if the folder needs to be deleted later.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][8]
• issueSignedToken · blob-issue-signed-token-no-try-catch

  error
  WhenissueSignedToken() throws BlobError on synchronous validation failures (missing options object, empty operations array, validUntil that is not a finite integer milliseconds timestamp, or validUntil <= now). It also throws BlobAccessError (auth failure), BlobStoreSuspendedError, BlobStoreNotFoundError, BlobServiceRateLimited, BlobServiceNotAvailable, or BlobUnknownError from the underlying requestApi() call to POST /signed-token.
  ThrowsBlobError, BlobAccessError, BlobStoreSuspendedError, BlobStoreNotFoundError, BlobServiceRateLimited, BlobServiceNotAvailable, or BlobUnknownError.
  Required handlingCaller MUST wrap issueSignedToken() in try-catch. This is the first call in the presigned-URL workflow — if it fails, no presigned URL can be issued and the entire client upload / signed-URL session is aborted. Sync validation errors (BlobError on bad validUntil) are programming errors that should be caught at request-time and surfaced as 400 to the client, not as 500. Auth errors should be surfaced as 401/500 depending on whether the request originated server-side or proxied a client request.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][9]
• issueSignedToken · blob-issue-signed-token-valid-until-in-past

  error
  WhenissueSignedToken() is called with validUntil that is <= Date.now() (a timestamp already in the past). This is a synchronous BlobError thrown before any network call. Common cause: passing a number-of-seconds (e.g. 3600) instead of an absolute ms timestamp (Date.now() + 3600 * 1000), or reusing a cached validUntil after the cache TTL elapsed.
  ThrowsBlobError: `issueSignedToken`: validUntil must be in the future.
  Required handlingAlways compute validUntil as Date.now() + ttlMs, not a duration. Validate the value is a future timestamp before calling. If signing tokens are pre-computed, recompute validUntil at issuance time, not at scheduling time.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• presignUrl · blob-presign-url-no-try-catch

  error
  WhenpresignUrl() throws BlobError synchronously for any of: missing clientSigningToken / delegationToken from the IssuedSignedToken pair, invalid or unreadable delegationToken payload, pathname mismatch (options.pathname does not match the scope encoded in the delegation), expired delegation (Date.now() > scope.validUntil), or operation not present in scope.operations (e.g. operation: 'put' against a get-only delegation).
  ThrowsBlobError (sync — clientSigningToken/delegationToken required, invalid delegation payload, pathname mismatch, expired delegation, operation not authorized).
  Required handlingCaller MUST wrap presignUrl() in try-catch. These are all programming errors except the expired-delegation case, which is the normal expiry path and must be handled by issuing a fresh token via issueSignedToken() and retrying. Returning a 5xx for expired-delegation is wrong UX — surface a 400 with "presigned URL expired, retry" so the client can re-request a token.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][9]
• presignUrl · blob-presign-url-delegation-expired

  warning
  WhenpresignUrl() is called with a signedToken whose scope.validUntil has already passed (Date.now() > scope.validUntil). This is the dominant expected-failure mode in production: signed tokens are short-lived (default 1 hour) and any retry or queued job picked up after the TTL window will throw. Treating this as a generic error buries the legitimate retry path.
  ThrowsBlobError: The signed delegation has expired; issue a new token first.
  Required handlingCatch this error explicitly and re-issue a fresh token via issueSignedToken(), then retry presignUrl(). Do NOT bubble it as a 5xx to the client — it is an expected condition. For background jobs, refresh the token at the start of each batch, not at job enqueue time.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• handleUploadPresigned · blob-handle-upload-presigned-no-try-catch

  error
  WhenhandleUploadPresigned() throws BlobError on missing/invalid request body, signature verification failure (BLOB_WEBHOOK_PUBLIC_KEY mismatch on the upload-completed callback), or BlobAccessError on missing/invalid token. It also re-throws any error thrown by the getSignedToken or onUploadCompleted callbacks. Webhook signature mismatch is the dominant failure mode — happens whenever the public key env var drifts from the keypair Vercel signs callbacks with.
  ThrowsBlobError (sync validation, signature verification failure), BlobAccessError (auth failure), or re-thrown errors from getSignedToken / onUploadCompleted callbacks.
  Required handlingThe outer route handler MUST wrap handleUploadPresigned() in try-catch and return an HTTP error response, not let the exception propagate. Signature-verification failures should be returned as 401 (callback rejected) — a 500 here would silently fail upload completion notifications. Validation errors from getSignedToken (e.g. pathname not allowed for this user) should be returned as 403.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• handleUploadPresigned · blob-handle-upload-presigned-missing-webhook-public-key

  error
  WhenhandleUploadPresigned() is called without webhookPublicKey AND BLOB_WEBHOOK_PUBLIC_KEY env var is not set. Upload-completed callbacks cannot be verified — either the handler will reject all callbacks (no key configured), or in worst case it will accept unsigned callbacks and let an attacker spoof "upload completed" events to trigger your onUploadCompleted business logic (e.g. database inserts) without an actual upload occurring.
  ThrowsBlobError on signature verification failure, or silently accepts spoofed callbacks if misconfigured.
  Required handlingSet BLOB_WEBHOOK_PUBLIC_KEY in your Vercel project env vars BEFORE deploying any route that uses handleUploadPresigned(). Treat a missing public key as a fatal startup error, not a warning. The keypair is generated by Vercel and must be fetched once via the dashboard.
  costhighin prodsilent failureusers seesecurity breachvisibilitysilent
  Sources[3]
• uploadPresigned · blob-upload-presigned-no-try-catch

  error
  WhenuploadPresigned() throws BlobError if handleUploadUrl is missing (programming error, synchronous), if the presigned-URL fetch from the server route fails (non-2xx or non-JSON response), if the presigned URL has expired between fetch and use (BlobClientTokenExpiredError-equivalent), or if the storage API rejects the upload (BlobAccessError, BlobFileTooLargeError, BlobServiceRateLimited, BlobUnknownError).
  ThrowsBlobError, BlobAccessError, BlobFileTooLargeError, BlobServiceRateLimited, BlobUnknownError, or BlobClientTokenExpiredError-equivalent.
  Required handlingCaller MUST wrap uploadPresigned() in try-catch. Distinguish expired-presigned-URL (retry by re-fetching) from auth-rejected (surface auth error to user) from size-too-large (surface file-size error). A single catch-all "upload failed" message buries the legitimate retry path for expired URLs.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.