Fix Astro `node:buffer` Build Error on Cloudflare Pages (2026)

Tested on: Astro 5.2, @astrojs/cloudflare 12.x, Cloudflare Pages
Symptom: npm run build passes locally. Cloudflare Pages build fails.

TL;DR

• Local npm run build passes; Cloudflare Pages fails resolving node:buffer.
• Add nodejs_compat compatibility flag in Cloudflare dashboard.
• Use @astrojs/cloudflare adapter with platformProxy.enabled: true.

The error

[vite]: Rollup failed to resolve import "node:buffer" from "astro/dist/..."
This is most likely unintended because it can break your application at runtime.

Cloudflare Pages build log, exit code 1. Local build: fine.

What I tried that didn't work

1. Adding node:buffer to vite.ssr.external — build passed but site returned 500 at runtime
2. Switching to @astrojs/node adapter — works, but defeats the purpose of Cloudflare edge deploy
3. npm install buffer — didn't help, wrong layer

What worked

astro.config.mjs:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server', // or 'hybrid'
  adapter: cloudflare({
    platformProxy: {
      enabled: true,
    },
  }),
});

And in Cloudflare Pages dashboard → Settings → Functions → Compatibility flags:

nodejs_compat

Also set Compatibility date to a recent date (e.g., 2024-09-23 or later).

Redeployed. Build passed. Site live.

Why this happens

Cloudflare Workers run on V8 isolates, not full Node.js. By default, node:* imports aren't available. The nodejs_compat flag enables a Node.js compatibility layer that Astro's Cloudflare adapter depends on.

Astro docs mention this but it's buried in the Cloudflare adapter page, not the main deployment guide.

Verify after deploy

# Check a server-rendered route
curl -I https://your-site.pages.dev/api/health
# Should return 200, not 500

# Check static pages still work
curl -I https://your-site.pages.dev/
# Should return 200 with text/html

My Cloudflare Pages build settings

Build command:    npm run build
Build output:     dist
Root directory:   /
Node version:     20

Environment variables:
  NODE_VERSION = 20

Compatibility flags (in dashboard, not in code):

nodejs_compat

Total debug time: ~1 hour. The fix itself is 30 seconds once you know about the flag.

FAQ

Why does Astro fail with node:buffer on Cloudflare Pages?

Cloudflare Workers run on V8 isolates, not full Node.js. Astro's Cloudflare adapter imports Node built-ins like node:buffer, which require the nodejs_compat flag.

Do I need nodejs_compat for static Astro sites?

Only if you use the Cloudflare adapter with server or hybrid output. Pure static export to Pages may not need it, but most Astro + CF adapter setups do.

Where do I set nodejs_compat on Cloudflare Pages?

Dashboard → your project → Settings → Functions → Compatibility flags → add nodejs_compat. Also set a recent compatibility date (2024-09-23 or later).