Astro Adapter Mismatch Between SSR and SSG Modes
Astro deploy fails or pages render blank because the adapter expects SSR but config says static, or vice versa — diagnose by aligning output, adapter, and route prerender flags.
🚢 Website & Deployment Issues
Vercel build, Firebase Hosting, Astro deploys, route 404s, sitemap, robots.txt.
Most deploy-stage errors aren`t code bugs — they`re tool config issues. Hub covers Vercel, Firebase Hosting, Astro / Next static sites: build failures, hangs, 500s, 404s, missing sitemap / robots.
Common problems
- Vercel build failed — fix it Three classic spots in the build log to read first.
- Vercel deploy stuck on "Building" OOM, dependency deadlock, build timeout — three causes.
- Vercel 500 errors — common causes Serverless function, env vars, edge runtime — three triages.
- Firebase Hosting deploy fails CLI version, quota, firebase.json — three common issues.
- Firebase Hosting route 404 Coming soon Missing rewrites, trailing slash, SPA fallback — typical.
- Astro pages 404 after deploy Align build.format, trailing slash, output mode.
- sitemap.xml not found Check @astrojs/sitemap integration and the `site` field.
- robots.txt not taking effect Static vs dynamic, CDN caching, Search Console tester.
- Build output exceeds platform size limit Bundle visualizer to find heavy deps; swap to lighter ones.
- Cloudflare Pages build cache stale Purge cache + commit package-lock + pin NODE_VERSION.
In-depth articles in this hub
Deploy Preview URLs Got Indexed by Google
Preview URLs from Vercel or Netlify appear in Google's index, often outranking your canonical domain — usually a missing noindex header or robots block on preview hosts.
GitHub Actions Deploy Step Times Out After 6 Hours
Your GitHub Actions deploy step hangs and gets cancelled at the 6-hour job limit — usually a wait-for-deployment poll, network egress block, or a deploy CLI waiting on missing input.
Monorepo Deploy Only Ships One App Out of Several
Your monorepo has three deployable apps but Vercel only deploys one — usually a root directory misconfig, ignored build command, or Turbo filter that swallows the others.
Netlify Function Cold Start Times Out at 10s
A Netlify Function works locally but the first request after idle returns a 502 with 'Task timed out after 10.00 seconds' — almost always cold-start init weight or upstream DNS.
Next.js ISR Revalidation Stuck Serving Stale Pages
An ISR page keeps serving cached HTML for hours past its revalidate window — almost always a CDN cache shadowing, build-output drift, or on-demand path mismatch.
Service Worker Serves Stale Bundle After Deploy
Users see the old site after you deploy because a service worker is caching the previous bundle and never picks up the new one — fix with skipWaiting, clean cache scope, and a kill switch.
Vercel Build Exceeds 45-Minute Limit and Cancels
Your Vercel build runs for 45 minutes and gets killed with 'Build exceeded maximum duration' — usually a cold cache, unbounded page generation, or a hung post-build step.
Canonical Wrong After Domain Change
Switched domains but old canonical still appears — config + cache.
Custom Domain SSL Provisioning Stuck
SSL pending for hours after domain hookup — usually DNS or CAA.
Deploy Succeeded But Page Still Shows Old Content
Vercel / Firebase says deploy ok, but visitors see yesterday's version.
DNS Propagation Confusion — Why Different Regions See Different IPs
You changed DNS and some users see new, some see old. Here's why and how to test.
Environment Variable Missing in Production
Works locally, fails prod — env var not set, or prefix issue (PUBLIC_ / VITE_ / NEXT_PUBLIC_).
How to Fix Firebase Hosting Route 404: SPA, SSG, Subpath — All Cases
After deploying to Firebase Hosting, the homepage works but /about and other subpages return 404? Your firebase.json rewrites are misconfigured. Fixes for SPA, SSG, static multipage, Astro, and Next.js.
OG Image Not Appearing on Social Shares
Share to LinkedIn / X / Slack and no image shows — meta tag, image size, or cache.
Redirects Not Working After Deploy
You configured redirects but they don't fire — order, format, host quirks.
RSS Feed Returns 404 — /rss.xml Missing Fix
/rss.xml or /feed.xml 404 — endpoint missing, wrong filename, or host caching.
Static Assets 404 After Deploy
Images and CSS 404 after deploy but work locally. Five typical causes — missing dist/ copy, base path, content hash, public folder, host upload step.
Static Site Renders Blank Page
Browser shows nothing, no error — almost always hydration or JS import failure.
Trailing Slash Mismatch — Double Redirects
/foo redirects to /foo/ then to /foo (or 308 → 301 chain). Pick one and stick to it.