image-optimizer: add configurable upstream fetch timeout

[TerryTaoYY]

Summary

This PR introduces a new experimental configuration option, experimental.imgFetchTimeoutInSeconds, to make the upstream fetch timeout used by Next.js Image Optimization configurable for remote images.

The default behavior is unchanged (7s). Setting the value to 0 disables the upstream fetch timeout (no AbortSignal.timeout is attached).

Motivation

Remote image optimization can fail on slower origins due to the hard-coded upstream fetch timeout. Making this timeout configurable allows applications to tune the bound while preserving Next.js’s default “bounded work” behavior.

Changes

• Add experimental.imgFetchTimeoutInSeconds to the Next.js config schema/shared config:

  • Must be a finite, non-negative integer.
  • undefined => default remains 7 seconds (no behavior change).
  • 0 => disable upstream fetch timeout (no AbortSignal.timeout; upstream waits can be unbounded).

• Apply the configured fetch timeout in the remote image fetch path used by /_next/image.

• Harden timeout detection and ensure stable error semantics:

  • TimeoutError is always treated as an upstream fetch timeout.
  • AbortError (including err.cause) is treated as an upstream fetch timeout only when a timeout signal was attached for that request.
  • Upstream fetch timeouts map to ImageError 504 with a stable code (e.g. IMAGE_FETCH_TIMEOUT).

• Documentation updates:

  • Document experimental.imgFetchTimeoutInSeconds for both App Router (next/image) and Pages Router legacy Image docs, including the 0 escape hatch and warning about unbounded waits.

Behavior / Compatibility

• Default behavior remains unchanged: upstream remote image fetch timeout is 7s unless configured.
• No redirect fallback is introduced; timeouts continue to surface as 504.
• This PR does not implement request header/cookie forwarding for remote images (out of scope; requires careful cache-key isolation and security considerations).

Config example

// next.config.js
module.exports = {
  experimental: {
    imgFetchTimeoutInSeconds: 30, // 0 disables the upstream fetch timeout
  },
}

Note: experimental.imgOptTimeoutInSeconds continues to control the Sharp processing timeout; this new option only affects the upstream fetch timeout.

Tests

• pnpm --filter next build
• pnpm jest --runTestsByPath test/unit/image-optimizer/fetch-external-image.test.ts
• pnpm jest --runTestsByPath test/integration/image-optimizer/test/index.test.ts

Related

• Allow customisation of upstream image timeout #72951 (configurable upstream timeout for remote image fetching)
• fetchExternalImage timesout and no way to change it #72072 (discussion around hard-coded upstream fetch timeout)
• _next/image endpoint does not forward along request headers #76931 (header forwarding for remote images; intentionally out of scope here)

[nextjs-bot]

Allow CI Workflow Run

• approve CI run for commit: 4e15e61

Note: this should only be enabled once the PR is ready to go and can only be enabled by a maintainer