Warning: `htmlLimitedBots` + `cacheComponents` Causes Download Issues in Vercel #85560

bolechen · 2025-10-30T11:38:32Z

bolechen
Oct 30, 2025

⚠️ Warning: `htmlLimitedBots` + `cacheComponents` Causes Download Issues in Vercel

TL;DR

DO NOT use htmlLimitedBots: /.*/ with Next.js 16's cacheComponents: true in production. It causes routes to trigger file downloads instead of rendering pages in Vercel deployments.

The Problem

When both configurations are enabled:

// next.config.ts
const nextConfig: NextConfig = {
  cacheComponents: true,        // ✅ Next.js 16 stable feature
  htmlLimitedBots: /.*/,        // ❌ Causes issues with cacheComponents
};

Symptoms:

✅ Works fine in local development (localhost:3000)
❌ Triggers file downloads in Vercel preview/production
❌ Browser downloads files like signin (1), page (1) instead of rendering HTML

Affected Routes:
Routes that combine:

"use cache" directive in layouts
Async searchParams: Promise<...>
Suspense boundaries

Why This Happens

htmlLimitedBots: /.*/ forces all user agents (including browsers) to wait for blocking metadata
Combined with Next.js 16's cacheComponents and "use cache" directives
Creates timing conflicts in Vercel's production environment
Results in malformed HTTP response headers
Browser receives incorrect or missing Content-Type: text/html header
Browser interprets response as downloadable file instead of HTML page

The Solution

Remove htmlLimitedBots entirely if using Next.js 16:

// next.config.ts
const nextConfig: NextConfig = {
  cacheComponents: true,
  // htmlLimitedBots: /.*/, // ← Remove this line
};

Why this works:

htmlLimitedBots was a workaround for Next.js 15.3.1 SEO issues (#79313)
Next.js 16 has improved metadata rendering and no longer needs this workaround
Native metadata handling in Next.js 16 is sufficient for SEO

Alternative Solutions

If you still need bot-specific metadata behavior, target only real bots:

// More specific regex - only affects known crawlers
htmlLimitedBots: /googlebot|bingbot|baiduspider|lighthouse/i,

This avoids affecting normal browser users while maintaining bot behavior.

Reproduction

Live Example (before fix):

Visit: https://pre.rushiwowen.co/auth/signin
Expected: Page renders
Actual: Browser downloads file

After removing htmlLimitedBots: ✅ Page renders correctly

Environment Details

Next.js: 16.0.1
React: 19.2.0
Deployment: Vercel
Issue: Preview and Production environments
Local: No issues

Related Issues

Original SEO issue: Metadata renders inside <body> instead of <head> after Next.js v15.3.1 #79313
This workaround is no longer needed in Next.js 16

Recommendation

For Next.js 16 users:

✅ Use cacheComponents: true (stable feature, works great!)
❌ Remove htmlLimitedBots: /.*/ (outdated workaround)
✅ Let Next.js 16 handle metadata natively

For Next.js 15 users:

Keep htmlLimitedBots if needed for SEO
Consider upgrading to Next.js 16 for better metadata handling

Hope this saves you hours of debugging! 🚀

If you encountered this issue, please react with 👍 to help others find this warning.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Warning: `htmlLimitedBots` + `cacheComponents` Causes Download Issues in Vercel #85560

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Warning: htmlLimitedBots + cacheComponents Causes Download Issues in Vercel #85560

Uh oh!

bolechen Oct 30, 2025

⚠️ Warning: htmlLimitedBots + cacheComponents Causes Download Issues in Vercel

TL;DR

The Problem

Why This Happens

The Solution

Alternative Solutions

Reproduction

Environment Details

Related Issues

Recommendation

Replies: 0 comments

Warning: `htmlLimitedBots` + `cacheComponents` Causes Download Issues in Vercel #85560

bolechen
Oct 30, 2025

⚠️ Warning: `htmlLimitedBots` + `cacheComponents` Causes Download Issues in Vercel