Common Errors

Real errors hit during builds and deploys, with fixes.

---

Cloudflare Pages build fails: ASSETS reserved binding

Error:

✘ [ERROR] "ASSETS" is a reserved binding name

Cause: @astrojs/cloudflare adapter v14+ auto-generates a wrangler.json that uses the reserved ASSETS binding name.

Fix: Remove the adapter entirely. Do not use @astrojs/cloudflare. Use Cloudflare Pages Functions (/functions/api/) for API routes instead. Delete any output: "server" or output: "hybrid" from astro.config.mjs.

---

Cloudflare Pages build fails: SESSION KV namespace

Error:

✘ [ERROR] "SESSION" KV namespace binding requires an `id`

Cause: Same as above - @astrojs/cloudflare adapter auto-provisions a SESSION KV binding.

Fix: Same - remove the adapter.

---

output: "hybrid" removed in Astro v7

Error:

Error: The value "hybrid" is not valid for the "output" option

Cause: Astro v7 removed the hybrid output mode.

Fix: Remove the output field entirely from astro.config.mjs. Astro v7 defaults to "static" and supports export const prerender = false on individual pages.

---

“Payment gateway not configured”

Cause: The Pages Function is reading import.meta.env.CASHFREE_APP_ID instead of context.env.CASHFREE_APP_ID.

Fix: In functions/api/payment/create-order.ts, always use:

const appId = env.CASHFREE_APP_ID; // from PagesContext.env

Never use import.meta.env for secrets in Cloudflare Functions.

---

“client session is invalid” (Cashfree)

Cause: Attempting to redirect directly to https://payments.cashfree.com/order/#SESSION_ID instead of using the JS SDK.

Fix: Use the Cashfree JS SDK:

const cashfree = window.Cashfree({ mode: "production" });
cashfree.checkout({ paymentSessionId: sessionId, redirectTarget: "_self" });

Direct URL redirects are not supported by Cashfree. The JS SDK is required.

---

522 error on www.domain.com

Cause: www.domain.com is not added as a custom domain in the Cloudflare Pages project.

Fix: In Cloudflare Pages -> project -> Custom domains -> add www.domain.com. Cloudflare creates the CNAME automatically.

---

OG image not showing in WhatsApp

Cause: WhatsApp aggressively caches link previews. If the link was shared before the image was added, WhatsApp shows the old cached (no-image) preview.

Fix:

1. Visit developers.facebook.com/tools/debug -> paste the URL -> click Scrape Again
2. Or share the URL with ?v=2 appended - WhatsApp treats it as a new URL and fetches fresh OG data

---

Edit tool: replace_all dropped trailing space

Cause: When replacing - (em dash with spaces) with -, the trailing space can be dropped if the replacement string doesn’t end with one.

Fix: Always check the result after em dash replacements and add back any missing spaces manually.

---

Google Maps iframe blank / CSP blocked

Cause: https://www.google.com is not in the frame-src directive in public/_headers.

Fix: Add it:

frame-src https://sdk.cashfree.com https://www.google.com;