Title: fetch() docs unclear about caching behavior for POST requests

[abhishekmardiya]

Goals

I was reading the fetch() documentation and noticed that it doesn't clearly mention how caching behaves for POST requests.

The docs explain caching options (cache, next.revalidate, etc.) , but it’s not explicit whether these options apply (or are ignored) for POST requests

Non-Goals

Background

The fetch() docs only explain caching for GET requests, leaving it unclear how caching behaves for POST. Some developers use POST for data retrieval (e.g., GraphQL queries or large payloads), so knowing whether options like cache: 'force-cache' or next.revalidate apply is important.

Proposal

It would be helpful to clarify:

Whether caching is supported for POST requests at all.

If not supported, whether the cache option is ignored or throws an error.

Any recommended approach for optimizing repeated POST requests.

This clarification would help developers understand the correct behavior and avoid confusion when using caching options with POST.

[icyJoseph]

Hi, yes, I've been wanting to find time to tackle this, #70946 - if you are willing to submit a PR, I'd appreciate that. If you do, make sure to verify the claims in the PR.

[abhishekmardiya]

I’ve reviewed the code and confirmed that the POST API requests are not cacheable. Since that’s the case, I can create a PR to update this documentation : https://nextjs.org/docs/app/api-reference/functions/fetch.

Reference:

POST requests cannot be cached because isCacheableRevalidate returns false for the POST method.

Reference lines:

next.js/packages/next/src/server/lib/patch-fetch.ts

Lines 577 to 583 in f52715b

	if (
	res.status === 200 &&
	staticGenerationStore.incrementalCache &&
	cacheKey &&
	isCacheableRevalidate
	) {
	const bodyBuffer = Buffer.from(await res.arrayBuffer())

next.js/packages/next/src/server/lib/patch-fetch.ts

Lines 491 to 493 in f52715b

	const isCacheableRevalidate =
	(typeof finalRevalidate === 'number' && finalRevalidate > 0) ||
	finalRevalidate === false

next.js/packages/next/src/server/lib/patch-fetch.ts

Lines 451 to 454 in f52715b

	} else if (autoNoCache) {
	finalRevalidate = 0
	cacheReason = 'auto no cache'
	} else {

next.js/packages/next/src/server/lib/patch-fetch.ts

Lines 378 to 397 in f52715b

	const isUnCacheableMethod = !['get', 'head'].includes(
	getRequestMeta('method')?.toLowerCase() || 'get'
	)
	// if there are authorized headers or a POST method and
	// dynamic data usage was present above the tree we bail
	// e.g. if cookies() is used before an authed/POST fetch
	// or no user provided fetch cache config or revalidate
	// is provided we don't cache
	const autoNoCache =
	// this condition is hit for null/undefined
	// eslint-disable-next-line eqeqeq
	(pageFetchCacheMode == undefined &&
	// eslint-disable-next-line eqeqeq
	currentFetchCacheConfig == undefined &&
	// eslint-disable-next-line eqeqeq
	currentFetchRevalidate == undefined) ||
	((hasUnCacheableHeader || isUnCacheableMethod) &&
	staticGenerationStore.revalidate === 0)

[icyJoseph]

What happens if I use cache: 'force-cache' though?

[abhishekmardiya]

Sorry, I missed that earlier — yes, POST requests can be cached when you explicitly set cache: "force-cache".

next.js/packages/next/src/server/lib/patch-fetch.ts

Lines 808 to 813 in 1111200

	if (
	res.status === 200 &&
	incrementalCache &&
	cacheKey &&
	(isCacheableRevalidate || serverComponentsHmrCache)
	) {

if (
  res.status === 200 &&        //  true (if response is 200)
  incrementalCache &&        //  true (available from workStore)
  cacheKey &&                     //  true
  (isCacheableRevalidate || serverComponentsHmrCache)  //  true (isCacheableRevalidate is true)
) {
  // This block WILL execute for POST requests with cache: "force-cache"
}

However, there’s a potential bug: when using the GET method with cache: "force-cache", requests that include headers or cookies can still pass the caching checks.

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer token123' // from 'next/headers'

  },
  cache: 'force-cache'
})

finalRevalidate = INFINITE_CACHE

next.js/packages/next/src/server/lib/patch-fetch.ts

Lines 593 to 600 in 1111200

	case 'force-cache': {
	if (
	typeof currentFetchRevalidate === 'undefined' ||
	currentFetchRevalidate === 0
	) {
	cacheReason = 'fetchCache = force-cache'
	finalRevalidate = INFINITE_CACHE
	}

isCacheableRevalidate = true

next.js/packages/next/src/server/lib/patch-fetch.ts

Lines 696 to 697 in 1111200

	const isCacheableRevalidate =
	typeof finalRevalidate === 'number' && finalRevalidate > 0

To fix this, we need to add proper checks to prevent force-cache from bypassing uncacheable headers, cookies, or methods.

Please let me know if I’ve missed anything or if there’s anything else that needs to be addressed.

[abhishekmardiya]

@icyJoseph
Following up on my earlier note — please let me know if there are any updates on this.