fix(blob): enforce maximumSizeInBytes client-side for multipart uploads (#1036)

For bodies with a known size (Blob, File, Buffer), check
maximumSizeInBytes before starting the multipart upload. This avoids
creating a multipart upload and uploading parts that will ultimately
be rejected by the server for exceeding the size limit.

Streams are skipped since their size is unknown upfront.

Fixes #873

Co-authored-by: Vincent Voyer <vincent@codeagain.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

.changeset/enforce-multipart-max-size.md

@@ -0,0 +1,5 @@
+---
+"@vercel/blob": patch
+---
+
+Enforce `maximumSizeInBytes` client-side for multipart uploads. Bodies with a known size (Blob, File, Buffer) are now checked before the upload starts, avoiding wasted API calls.

packages/blob/src/helpers.ts

@@ -64,6 +64,14 @@ export interface CommonCreateBlobOptions extends BlobCommandOptions {
    * If the ETag doesn't match, a `BlobPreconditionFailedError` will be thrown.
    */
   ifMatch?: string;
+  /**
+   * Maximum size in bytes allowed for this upload. Currently only enforced
+   * client-side for multipart uploads (`put(..., { multipart: true })`).
+   * For bodies with a known size (Blob, File, Buffer, etc.) the check is
+   * performed before the upload starts. Streams cannot be checked upfront.
+   * The maximum allowed value is 5TB.
+   */
+  maximumSizeInBytes?: number;
 }
 
 /**

packages/blob/src/index.node.test.ts

@@ -753,6 +753,44 @@ describe('blob client', () => {
       );
     });
 
+    it('throws when body exceeds maximumSizeInBytes in a multipart put', async () => {
+      const largeBody = new Blob([new Uint8Array(1024)]); // 1 KB
+      await expect(
+        put('foo.txt', largeBody, {
+          access: 'public',
+          multipart: true,
+          maximumSizeInBytes: 512, // 512 bytes limit
+        }),
+      ).rejects.toThrow(
+        new Error(
+          'Vercel Blob: Body size of 1024 bytes exceeds the maximum allowed size of 512 bytes',
+        ),
+      );
+    });
+
+    it('does not throw client-side size error for stream body with maximumSizeInBytes in a multipart put', async () => {
+      const stream = new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode('hello'));
+          controller.close();
+        },
+      });
+
+      // Should not throw the client-side size error — streams have unknown
+      // length, so maximumSizeInBytes enforcement is deferred to the server.
+      try {
+        await put('foo.txt', stream, {
+          access: 'public',
+          multipart: true,
+          maximumSizeInBytes: 1,
+        });
+      } catch (error) {
+        expect((error as Error).message).not.toMatch(
+          /Body size of .* bytes exceeds the maximum allowed size/,
+        );
+      }
+    });
+
     const table: [string, (signal: AbortSignal) => Promise<unknown>][] = [
       [
         'put',

packages/blob/src/multipart/uncontrolled.ts

@@ -1,6 +1,6 @@
 import { debug } from '../debug';
-import type { BlobCommandOptions, WithUploadProgress } from '../helpers';
-import { computeBodyLength } from '../helpers';
+import type { CommonCreateBlobOptions, WithUploadProgress } from '../helpers';
+import { BlobError, computeBodyLength, isStream } from '../helpers';
 import type { PutBlobResult, PutBody } from '../put-helpers';
 import { completeMultipartUpload } from './complete';
 import { createMultipartUpload } from './create';
@@ -12,7 +12,7 @@ export async function uncontrolledMultipartUpload(
   pathname: string,
   body: PutBody,
   headers: Record<string, string>,
-  options: BlobCommandOptions & WithUploadProgress,
+  options: CommonCreateBlobOptions & WithUploadProgress,
 ): Promise<PutBlobResult> {
   debug('mpu: init', 'pathname:', pathname, 'headers:', headers);
 
@@ -21,6 +21,20 @@ export async function uncontrolledMultipartUpload(
     onUploadProgress: undefined,
   };
 
+  // For bodies with a known size (Blob, File, Buffer, etc.) enforce
+  // maximumSizeInBytes client-side before starting the upload. This avoids
+  // creating a multipart upload that will ultimately fail.
+  // Streams are skipped because their size is unknown upfront.
+  if (
+    options.maximumSizeInBytes !== undefined &&
+    !isStream(body) &&
+    computeBodyLength(body) > options.maximumSizeInBytes
+  ) {
+    throw new BlobError(
+      `Body size of ${computeBodyLength(body)} bytes exceeds the maximum allowed size of ${options.maximumSizeInBytes} bytes`,
+    );
+  }
+
   // Step 1: Start multipart upload
   const createMultipartUploadResponse = await createMultipartUpload(
     pathname,