[recovery] Disable Next image on-disk cache on read-only Netlify Lambda

[pettinarip]

Error

Recurring unhandled promise rejection in the ___netlify-server-handler function (11 hits, first seen 2026-05-25):

[ERROR] Unhandled Promise Rejection {"errorType":"Runtime.UnhandledPromiseRejection",
"errorMessage":"Error: ENOENT: no such file or directory, mkdir '/var/task/.next/cache'",
... at .../next/dist/server/lib/disk-lru-cache.external.js:36:17}

Root cause

Next.js 16's image optimizer (ImageOptimizerCache, next/dist/server/image-optimizer.js:686-694) eagerly initializes an on-disk LRU cache in its constructor whenever:

• no custom cacheHandler is set, and
• images.maximumDiskCacheSize !== 0, and
• experimental.isrFlushToDisk is truthy

All three hold by default in our config. That eager getOrInitDiskLRU(...) promise (disk-lru-cache.external.js:36) calls fs.promises.mkdir(cacheDir, { recursive: true }) where cacheDir = .next/cache/images. On Netlify's read-only Lambda filesystem (/var/task), creating .next/cache fails with ENOENT.

Because the promise is created eagerly in the constructor and not awaited or caught at that point (only later inside get()/set()), the rejection escapes as an unhandled promise rejection and crashes/pollutes the server handler.

Fix

Set images.maximumDiskCacheSize: 0 in next.config.js. Per the constructor guard, this leaves isDiskCacheEnabled false so getOrInitDiskLRU is never called — no mkdir, no rejection.

maximumDiskCacheSize is a documented public image option (z.number().int().min(0).optional() in Next's config schema). The local disk image cache is useless on ephemeral, read-only Lambda anyway — optimized images are served through Netlify's image CDN (NEXT_FORCE_EDGE_IMAGES=true), so there is no functional regression.

Affected files

• next.config.js

Verification

• pnpm type-check ✅
• pnpm exec eslint next.config.js ✅ (clean)

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for ethereumorg ready!

Name	Link
🔨 Latest commit	e6ba8cc
🔍 Latest deploy log	https://app.netlify.com/projects/ethereumorg/deploys/6a57ad7f1f3d740007aa8dac
😎 Deploy Preview	https://deploy-preview-18781.ethereum.it
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	7 paths audited Performance: 61 (🟢 up 5 from production) Accessibility: 95 (no change from production) Best Practices: 100 (no change from production) SEO: 98 (no change from production) PWA: 59 (🔴 down 1 from production) View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

🔎 First-pass review — ✅ Looks mergeable

Sets images.maximumDiskCacheSize: 0 in next.config.js to stop Next 16's image optimizer from eagerly calling mkdir('.next/cache/images') on Netlify's read-only Lambda FS, which was surfacing as a recurring unhandled promise rejection. The diagnosis is accurate and the fix is minimal (4 lines, comment + one option). Verified NEXT_FORCE_EDGE_IMAGES="true" is set in netlify.toml, so optimized images are already served via Netlify's image CDN — disabling the local disk LRU is a no-op functionally on Lambda. No convention issues.

Analysis

• Lane: tooling (single config file, next.config.js)
• Checked: option placement within images config ✅; maximumDiskCacheSize is a documented public image option; CDN claim verified against netlify.toml:18 (NEXT_FORCE_EDGE_IMAGES="true") ✅; no functional regression on the edge-image path.
• Non-blocking: none. CI may still be running — no failing checks observed.

Generated by PR Reviewer (team) for #18781 · 55.2 AIC · ⌖ 27.4 AIC · ⊞ 5.2K · ◷

[coderabbitai]

Caution

Review failed

An error occurred during the review process. Please try again later.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch recovery/fix/image-disk-cache-readonly-lambda

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}