feat(next/image)!: add images.maximumResponseBody config (#88183)

styfle · unstubbable · commit 39a2f6a8d13d · 2026-01-26T18:09:19.000+01:00
Add `images.maximumResponseBody` configuration to exit early when
attempting to optimize large source images.
diff --git a/crates/next-build-test/nextConfig.json b/crates/next-build-test/nextConfig.json
@@ -30,6 +30,7 @@
     "disableStaticImages": false,
     "minimumCacheTTL": 60,
     "formats": ["image/avif", "image/webp"],
+    "maximumResponseBody": 300000000,
     "dangerouslyAllowSVG": false,
     "contentSecurityPolicy": "script-src 'none'; frame-src 'none'; sandbox;",
     "contentDispositionType": "inline",
diff --git a/docs/01-app/03-api-reference/02-components/image.mdx b/docs/01-app/03-api-reference/02-components/image.mdx
@@ -774,6 +774,28 @@ module.exports = {
 }
 ```
 
+#### `maximumResponseBody`
+
+The default image optimization loader will fetch source images up to 300 MB in size.
+
+```js filename="next.config.js"
+module.exports = {
+  images: {
+    maximumResponseBody: 300_000_000,
+  },
+}
+```
+
+If you know all your source images are small, you can protect memory constrained servers by reducing this to a smaller value such as 50 MB.
+
+```js filename="next.config.js"
+module.exports = {
+  images: {
+    maximumResponseBody: 50_000_000,
+  },
+}
+```
+
 #### `dangerouslyAllowSVG`
 
 `dangerouslyAllowSVG` allows you to serve SVG images.
diff --git a/packages/next/src/server/config-schema.ts b/packages/next/src/server/config-schema.ts
@@ -654,6 +654,12 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
           .optional(),
         loader: z.enum(VALID_LOADERS).optional(),
         loaderFile: z.string().optional(),
+        maximumResponseBody: z
+          .number()
+          .int()
+          .min(1)
+          .max(Number.MAX_SAFE_INTEGER)
+          .optional(),
         minimumCacheTTL: z.number().int().gte(0).optional(),
         path: z.string().optional(),
         qualities: z
diff --git a/packages/next/src/server/image-optimizer.ts b/packages/next/src/server/image-optimizer.ts
@@ -694,7 +694,10 @@ export async function optimizeImage({
   return optimizedBuffer
 }
 
-export async function fetchExternalImage(href: string): Promise<ImageUpstream> {
+export async function fetchExternalImage(
+  href: string,
+  maximumResponseBody: number
+): Promise<ImageUpstream> {
   const res = await fetch(href, {
     signal: AbortSignal.timeout(7_000),
   }).catch((err) => err as Error)
@@ -719,7 +722,35 @@ export async function fetchExternalImage(href: string): Promise<ImageUpstream> {
     )
   }
 
-  const buffer = Buffer.from(await res.arrayBuffer())
+  if (!res.body) {
+    Log.error('upstream image response is empty for', href)
+    throw new ImageError(
+      400,
+      '"url" parameter is valid but upstream response is invalid'
+    )
+  }
+
+  const chunks: Buffer[] = []
+  let totalSize = 0
+
+  for await (const c of res.body) {
+    const chunk = Buffer.from(c)
+    totalSize += chunk.byteLength
+    if (totalSize > maximumResponseBody) {
+      Log.error(
+        'upstream image response exceeded maximum size for',
+        href,
+        totalSize
+      )
+      throw new ImageError(
+        413,
+        '"url" parameter is valid but upstream response is invalid'
+      )
+    }
+    chunks.push(chunk)
+  }
+
+  const buffer = Buffer.concat(chunks)
   const contentType = res.headers.get('Content-Type')
   const cacheControl = res.headers.get('Cache-Control')
   const etag = extractEtag(res.headers.get('ETag'), buffer)
diff --git a/packages/next/src/server/next-server.ts b/packages/next/src/server/next-server.ts
@@ -786,7 +786,10 @@ export default class NextNodeServer extends BaseServer<
       const { isAbsolute, href } = paramsResult
 
       const imageUpstream = isAbsolute
-        ? await fetchExternalImage(href)
+        ? await fetchExternalImage(
+            href,
+            this.nextConfig.images.maximumResponseBody
+          )
         : await fetchInternalImage(
             href,
             req.originalRequest,
diff --git a/packages/next/src/shared/lib/image-config.ts b/packages/next/src/shared/lib/image-config.ts
@@ -103,6 +103,9 @@ export type ImageConfigComplete = {
   /** @see [Acceptable formats](https://nextjs.org/docs/api-reference/next/image#acceptable-formats) */
   formats: ImageFormat[]
 
+  /** @see [Maximum Response Body](https://nextjs.org/docs/api-reference/next/image#maximumresponsebody) */
+  maximumResponseBody: number
+
   /** @see [Dangerously Allow SVG](https://nextjs.org/docs/api-reference/next/image#dangerously-allow-svg) */
   dangerouslyAllowSVG: boolean
 
@@ -137,6 +140,7 @@ export const imageConfigDefault: ImageConfigComplete = {
   disableStaticImages: false,
   minimumCacheTTL: 60,
   formats: ['image/webp'],
+  maximumResponseBody: 300_000_000, // 300MB
   dangerouslyAllowSVG: false,
   contentSecurityPolicy: `script-src 'none'; frame-src 'none'; sandbox;`,
   contentDispositionType: 'attachment',
diff --git a/test/integration/next-image-new/app-dir-localpatterns/test/index.test.ts b/test/integration/next-image-new/app-dir-localpatterns/test/index.test.ts
@@ -96,6 +96,7 @@ function runTests(mode: 'dev' | 'server') {
               search: '',
             },
           ],
+          maximumResponseBody: 300000000,
           minimumCacheTTL: 60,
           path: '/_next/image',
           qualities: undefined,
diff --git a/test/integration/next-image-new/app-dir-qualities/test/index.test.ts b/test/integration/next-image-new/app-dir-qualities/test/index.test.ts
@@ -107,6 +107,7 @@ function runTests(mode: 'dev' | 'server') {
           loaderFile: '',
           remotePatterns: [],
           localPatterns: undefined,
+          maximumResponseBody: 300000000,
           minimumCacheTTL: 60,
           path: '/_next/image',
           qualities: [42, 69, 88],
diff --git a/test/integration/next-image-new/app-dir/test/index.test.ts b/test/integration/next-image-new/app-dir/test/index.test.ts
@@ -1634,6 +1634,7 @@ function runTests(mode: 'dev' | 'server') {
           loaderFile: '',
           remotePatterns: [],
           localPatterns: undefined,
+          maximumResponseBody: 300000000,
           minimumCacheTTL: 60,
           path: '/_next/image',
           qualities: undefined,
diff --git a/test/integration/next-image-new/unicode/test/index.test.ts b/test/integration/next-image-new/unicode/test/index.test.ts
@@ -94,6 +94,7 @@ function runTests(mode: 'server' | 'dev') {
               search: '',
             },
           ],
+          maximumResponseBody: 300000000,
           minimumCacheTTL: 60,
           path: '/_next/image',
           sizes: [
diff --git a/test/integration/next-image-new/unoptimized/test/index.test.ts b/test/integration/next-image-new/unoptimized/test/index.test.ts
@@ -110,6 +110,7 @@ function runTests(url: string, mode: 'dev' | 'server') {
           loaderFile: '',
           remotePatterns: [],
           localPatterns: undefined,
+          maximumResponseBody: 300000000,
           minimumCacheTTL: 60,
           path: '/_next/image',
           qualities: undefined,
diff --git a/test/unit/image-optimizer/fetch-external-image.test.ts b/test/unit/image-optimizer/fetch-external-image.test.ts
@@ -0,0 +1,183 @@
+/* eslint-env jest */
+import {
+  fetchExternalImage,
+  ImageError,
+} from 'next/dist/server/image-optimizer'
+
+describe('fetchExternalImage', () => {
+  describe('response size limit', () => {
+    it('should throw error when response has no body', async () => {
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        body: null,
+        headers: {
+          get: jest.fn(() => null),
+        },
+      })
+
+      const error = await fetchExternalImage(
+        'http://example.com/no-body.jpg',
+        300_000_000
+      ).catch((e) => e)
+
+      expect(error).toBeInstanceOf(ImageError)
+      expect((error as ImageError).statusCode).toBe(400)
+      expect((error as ImageError).message).toBe(
+        '"url" parameter is valid but upstream response is invalid'
+      )
+    })
+
+    it('should throw error when exceeding maximumResponseBody config on later chunk', async () => {
+      const maximumResponseBody = 2_000 // 2KB custom limit
+      const chunkSize = 1_000 // 1KB chunks
+      const numChunks = 3 // 3KB total, exceeds custom 2KB limit
+
+      global.fetch = jest.fn().mockImplementation(() => {
+        let chunksRead = 0
+        const mockReadableStream = new ReadableStream({
+          async pull(controller) {
+            if (chunksRead < numChunks) {
+              controller.enqueue(new Uint8Array(chunkSize))
+              chunksRead++
+            } else {
+              controller.close()
+            }
+          },
+        })
+
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          body: mockReadableStream,
+          headers: {
+            get: jest.fn((header: string) => {
+              if (header === 'Content-Type') return 'image/jpeg'
+              return null
+            }),
+          },
+        })
+      })
+
+      const error = await fetchExternalImage(
+        'http://example.com/custom-limit.jpg',
+        maximumResponseBody
+      ).catch((e) => e)
+
+      expect(error).toBeInstanceOf(ImageError)
+      expect((error as ImageError).statusCode).toBe(413)
+      expect((error as ImageError).message).toBe(
+        '"url" parameter is valid but upstream response is invalid'
+      )
+    })
+
+    it('should throw error when exceeding maximumResponseBody config on first chunk', async () => {
+      const maximumResponseBody = 2_000 // 2KB custom limit
+
+      global.fetch = jest.fn().mockImplementation(() => {
+        const mockReadableStream = new ReadableStream({
+          async pull(controller) {
+            controller.enqueue(new Uint8Array(maximumResponseBody + 1))
+            controller.close()
+          },
+        })
+
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          body: mockReadableStream,
+          headers: {
+            get: jest.fn((header: string) => {
+              if (header === 'Content-Type') return 'image/jpeg'
+              return null
+            }),
+          },
+        })
+      })
+
+      const error = await fetchExternalImage(
+        'http://example.com/custom-limit.jpg',
+        maximumResponseBody
+      ).catch((e) => e)
+
+      expect(error).toBeInstanceOf(ImageError)
+      expect((error as ImageError).statusCode).toBe(413)
+      expect((error as ImageError).message).toBe(
+        '"url" parameter is valid but upstream response is invalid'
+      )
+    })
+
+    it('should succeed when exactly matching maximumResponseBody config on first chunk', async () => {
+      const maximumResponseBody = 3_000 // 3KB custom limit
+
+      global.fetch = jest.fn().mockImplementation(() => {
+        const mockReadableStream = new ReadableStream({
+          async pull(controller) {
+            controller.enqueue(new Uint8Array(maximumResponseBody))
+            controller.close()
+          },
+        })
+
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          body: mockReadableStream,
+          headers: {
+            get: jest.fn((header: string) => {
+              if (header === 'Content-Type') return 'image/jpeg'
+              return null
+            }),
+          },
+        })
+      })
+
+      const result = await fetchExternalImage(
+        'http://example.com/custom-limit.jpg',
+        maximumResponseBody
+      )
+
+      expect(result.buffer).toBeInstanceOf(Buffer)
+      expect(result.buffer.length).toBe(maximumResponseBody)
+    })
+
+    it('should succeed when exactly matching maximumResponseBody config on later chunk', async () => {
+      const maximumResponseBody = 3_000 // 3KB custom limit
+      const chunkSize = 1_000 // 1KB chunks
+      const numChunks = 3 // 3KB total
+
+      global.fetch = jest.fn().mockImplementation(() => {
+        let chunksRead = 0
+        const mockReadableStream = new ReadableStream({
+          async pull(controller) {
+            if (chunksRead < numChunks) {
+              controller.enqueue(new Uint8Array(chunkSize))
+              chunksRead++
+            } else {
+              controller.close()
+            }
+          },
+        })
+
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          body: mockReadableStream,
+          headers: {
+            get: jest.fn((header: string) => {
+              if (header === 'Content-Type') return 'image/jpeg'
+              return null
+            }),
+          },
+        })
+      })
+
+      const result = await fetchExternalImage(
+        'http://example.com/custom-limit.jpg',
+        maximumResponseBody
+      )
+
+      expect(result.buffer).toBeInstanceOf(Buffer)
+      expect(result.buffer.length).toBe(maximumResponseBody)
+    })
+  })
+})
