Constraints

Constraints are the two limits an upload route enforces before it signs anything: how big a file may be, and what type it may be.

// lib/uploads.tsimport { uploadHandler, uniquePath } from "@upstash/blob"export const uploads = uploadHandler({  constraints: { maxSize: "20mb", contentTypes: ["image/*", "application/pdf"] },  onBeforeUpload: ({ file }) => ({ path: uniquePath(`uploads/${file.name}`) }),})

# app/uploads.pyfrom upstash_blob import AsyncUploadHandler, BeforeUploadResult, unique_pathuploads = AsyncUploadHandler(    max_size="20mb",    content_types=["image/*", "application/pdf"],    on_before_upload=lambda args: BeforeUploadResult(path=unique_path(f"uploads/{args.file.name}")),)

// uploads.gouploads, err := blob.NewUploadHandler(blob.UploadHandlerOptions[struct{}]{	MaxSize:      20 * blob.MB,	ContentTypes: []string{"image/*", "application/pdf"},	OnBeforeUpload: func(		a blob.BeforeUploadArgs[struct{}],	) (blob.BeforeUploadResult, error) {		path := blob.UniquePath("uploads/" + a.File.Name)		return blob.BeforeUploadResult{Path: path}, nil	},})

They are checked at begin, from the name, type and size the browser declared, before the before-upload callback runs. A refused file leaves nothing behind: no presigned URL, no row, no multipart upload.

Omitting constraints accepts any type at any size. The option names in each SDK: TypeScript, Python, Go.

In the constraints document served to the browser they are maxSize and contentTypes.

Max size#

constraints: { maxSize: "2MB" }   // 2,000,000 bytesconstraints: { maxSize: "32MiB" } // 33,554,432 bytesconstraints: { maxSize: 4096 }    // a bare number is bytes

max_size="2MB"    # 2,000,000 bytesmax_size="32MiB"  # 33,554,432 bytesmax_size=4096     # a bare int is bytes

MaxSize: 2 * blob.MB   // 2,000,000 bytesMaxSize: 32 * blob.MiB // 33,554,432 bytesMaxSize: 4096          // always bytes

The max size takes a Size, always in bytes. MB uses powers of 1,000; MiB uses powers of 1,024. Units ignore case. To accept a 32 MiB file, set it to "32MiB" or 33554432. "32mb" means 32,000,000 bytes and is too small for that file.

Refusal messages display decimal byte units, or exact bytes when the file and the limit would round to the same text:

cat.png is 2.4 MB, over the 2 MB limit

An unparseable size throws where the option is written, at startup, not once per request. In Go a size is an int64 and cannot be unparseable; blob.ParseSize reads one from configuration.

Content types#

constraints: { contentTypes: ["image/*", "application/pdf", "image/svg+xml"] }

content_types=["image/*", "application/pdf", "image/svg+xml"]

ContentTypes: []string{"image/*", "application/pdf", "image/svg+xml"}

Each entry is either an exact type/subtype, or one of three wildcards: image/*, video/* and audio/*.

Anything else throws invalid_content_type_pattern: */*, text/*, and strings that are not a media type (png, image/, /png). An empty list throws too; omit the option to accept anything.

What the wildcards expand to#

Aliases#

Browsers and operating systems send several spellings for some types. Both the declared type and your list are canonicalized before comparison, so a list of ['image/jpg'] accepts a file declared image/jpeg, and the reverse. Parameters are stripped, so image/png; charset=binary is image/png.

Byte sniffing#

A route with content types checks more than the declared type. The browser sends the file’s leading bytes with the begin request, so a mislabelled file is refused before the upload rather than after it. Two checks run:

1. The declared type must be in the allow list. A report.exe declared as application/x-msdownload is refused here.
2. The leading bytes must not clearly contradict the declared type. If the bytes prove nothing, the file passes.

The second check is lenient on purpose so real files are not refused. A .docx really is a zip, and so are .epub, .jar and .apk. Formats that share a signature, like mp4 and heic, or webm and mkv, never contradict a declaration. Neither does application/octet-stream.

Per-route constraints#

// lib/uploads.tsexport const uploads = uploadHandler({  constraints: { maxSize: "20mb", contentTypes: ["image/png"] },  routes: {    attachment: {      onBeforeUpload: () => ({ path: "attachment/1.png" }),    },    avatar: {      constraints: { maxSize: "2mb" },      onBeforeUpload: () => ({ path: "avatar/demo" }),    },    large: {      constraints: { maxSize: "2gb", contentTypes: null },      onBeforeUpload: () => ({ path: "large/1.bin" }),    },  },})

# app/uploads.pyuploads = AsyncUploadHandler(    max_size="20mb",    content_types=["image/png"],    routes={        "attachment": UploadRoute(            on_before_upload=lambda args: BeforeUploadResult(path="attachment/1.png"),        ),        "avatar": UploadRoute(            max_size="2mb",            on_before_upload=lambda args: BeforeUploadResult(path="avatar/demo"),        ),        "large": UploadRoute(            max_size="2gb",            content_types=None,            on_before_upload=lambda args: BeforeUploadResult(path="large/1.bin"),        ),    },)

// uploads.gopaths := map[string]string{	"attachment": "attachment/1.png",	"avatar":     "avatar/demo",	"large":      "large/1.bin",}uploads, err := blob.NewUploadHandler(blob.UploadHandlerOptions[struct{}]{	MaxSize:      20 * blob.MB,	ContentTypes: []string{"image/png"},	OnBeforeUpload: func(		a blob.BeforeUploadArgs[struct{}],	) (blob.BeforeUploadResult, error) {		return blob.BeforeUploadResult{Path: paths[a.Route]}, nil	},	Routes: map[string]blob.UploadRoute[struct{}]{		"attachment": {},		"avatar":     {MaxSize: 2 * blob.MB},		"large":      {MaxSize: 2 * blob.GB, ContentTypes: []string{}},	},})

A route’s constraints override the handler’s key by key. A key the route does not mention is inherited. An explicit null (None in Python) clears a key the handler set. In Go, where a zero value means inherit, an empty ContentTypes slice or MaxSize: blob.NoLimit clears it.

Narrowing per user#

// lib/uploads.tsonBeforeUpload: async ({ request, file }) => {  const user = await getUser(request)  return {    path: uniquePath(`${user.id}/${file.name}`),    constraints: user.plan === "free" ? { maxSize: "25mb", contentTypes: ["image/*"] } : undefined,  }},

# app/uploads.pyasync def authorize(args: BeforeUploadArgs) -> BeforeUploadResult:    user = await get_user(args.request)    free = user.plan == "free"    return BeforeUploadResult(        path=unique_path(f"{user.id}/{args.file.name}"),        max_size="25mb" if free else None,        content_types=["image/*"] if free else None,    )

// uploads.gofunc authorize(	a blob.BeforeUploadArgs[*User],) (blob.BeforeUploadResult, error) {	path := blob.UniquePath(a.Ctx.ID + "/" + a.File.Name)	res := blob.BeforeUploadResult{Path: path}	if a.Ctx.Plan == "free" {		res.MaxSize = 25 * blob.MB		res.ContentTypes = []string{"image/*"}	}	return res, nil}

The before-upload callback may return constraints to tighten the route’s limits for this one upload, once it knows who is uploading. They are checked against the same file right after it returns. Widening throws, so a route’s code always shows the most it can accept.

In the browser#

{ "protocol": 1, "constraints": { "contentTypes": ["image/png"], "maxSize": 2000000 } }

GET on the upload route serves the constraints it enforces, cached for 60 seconds, so a deploy that changes a route’s limits reaches clients within a minute.

useUpload exposes two things from it. accept is contentTypes joined with commas, ready for an <input accept>. constraints is the served document itself, so a page can show the limit it enforces.

"use client"import { formatBytes } from "@upstash/blob/react"import { useUpload } from "@/lib/upload-hooks"export function UploadButton() {  const { start, upload, accept, constraints } = useUpload()  return (    <>      <input type="file" accept={accept} onChange={(e) => start({ file: e.target.files?.[0] })} />      {constraints?.maxSize !== undefined && <p>Up to {formatBytes(constraints.maxSize)}</p>}      {upload?.error && <p>{upload.error.message}</p>}    </>  )}

A file over the max size is refused in the browser before any request is made. It still becomes a record with status: 'error' and a BlobError with code too_large, so one error path renders both the client-side refusal and the server’s.

The size check is the only one that runs in the browser. The server is authoritative for everything else. If the constraints have not arrived yet, the file is simply sent and the route decides.

Error codes#

A refusal here is too_large, content_type_not_allowed, invalid_content_type_pattern or empty_body. It reaches the browser as a BlobError with that code intact, so switch on error.code rather than on status numbers. See Errors.

Server-side writes#

put takes the same content types and max size options, with the same grammar, aliases and byte check, for bytes that pass through your own route. See Writing.