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;

---

Build fails: updatedDate invalid date

Error:

Error: Invalid Date
  at src/content/blog/your-post.md: updatedDate

Cause: Sveltia CMS writes updatedDate: "" (empty string) when the field is left blank. z.coerce.date("") silently produces an Invalid Date object that fails Zod validation at build time.

Fix: Use a union type in content.config.ts:

updatedDate: z.union([z.coerce.date(), z.literal(''), z.null()]).optional(),

---

VS Code: cascade never type errors after editing content.config.ts

Error:

Property 'data' does not exist on type 'never'
Property 'title' does not exist on type 'never'

Appears in every file that calls getCollection after you add or change a field in content.config.ts.

Cause: The Astro language server has a stale .astro/types.d.ts cache.

Fix: npm run build is the source of truth. If it passes without errors, the VS Code errors are false positives. Clear them by restarting the TypeScript server: Ctrl+Shift+P → “TypeScript: Restart TS Server”.

---

FAQPage TypeScript: implicit any on map callback

Error:

Parameter 'f' implicitly has an 'any' type.

Cause: In strict TypeScript mode, the .map() callback on post.data.faqs needs an explicit type annotation.

Fix:

// Wrong
const faqs = post.data.faqs ?? [];
faqs.map((f) => f.q)  // ← f is implicit any

// Correct
faqs.map((f: { q: string; a: string }) => ({
  '@type': 'Question',
  name: f.q,
  acceptedAnswer: { '@type': 'Answer', text: f.a },
}))

Also extract const faqs = post.data.faqs ?? [] before using .length — calling post.data.faqs?.length without the null-coalesce first can cause TypeScript to narrow the type to never.

---

Pages not getting indexed / “Referring page: None detected” in GSC

Symptom: Google Search Console shows pages as “Discovered — currently not indexed” with “Referring page: None detected”. Pages aren’t appearing in search results.

Cause (technical): noindex pages are included in the sitemap. Google sees a contradictory signal — the sitemap says “crawl this” but the meta tag says “noindex”. This can suppress crawling of the whole site.

Check dist/sitemap-0.xml after a build. If /checkout/, /payment-return/, or /thank-you/ appear there, the filter is missing.

Fix: Add a filter to the sitemap integration in astro.config.mjs:

integrations: [
  sitemap({
    filter: (page) =>
      !page.includes("/checkout") &&
      !page.includes("/payment-return") &&
      !page.includes("/thank-you"),
  }),
],

This is already set in juju-template’s astro.config.mjs. Don’t remove it.

Cause (“Referring page: None detected”): This is a separate, expected message. It means Google found the URL via sitemap, not by following an internal link. Not an error — no fix needed.

After deploying the fix:

1. Go to Google Search Console → Sitemaps → resubmit the sitemap URL
2. For key pages, use URL Inspection → Request Indexing
3. New domains typically take 4–8 weeks to index regardless of technical correctness