website-enchun-mgr/.agent/skills/astro-cloudflare-deploy/references/troubleshooting.md

Troubleshooting Guide

This guide covers common issues when deploying Astro 6 to Cloudflare Workers.

Table of Contents

1. Build Errors
2. Runtime Errors
3. Deployment Issues
4. Performance Issues
5. Development Server Issues

---

Build Errors

"MessageChannel is not defined"

Symptoms:

• Build fails with reference to MessageChannel
• Occurs when using React 19 with Cloudflare adapter

Cause: React 19 uses MessageChannel which is not available in the Cloudflare Workers runtime by default.

Solutions:

1. Add compatibility flag in wrangler.jsonc:

   {
     "compatibility_flags": ["nodejs_compat"]
   }
   

2. Use React 18 temporarily if the issue persists:

   npm install react@18 react-dom@18
   

3. Check for related GitHub issues:

   • Astro Issue #12824

"Cannot find module '@astrojs/cloudflare'"

Symptoms:

• Import error in astro.config.mjs
• Type errors in TypeScript

Solutions:

1. Install the adapter:

   npm install @astrojs/cloudflare
   

2. Verify installation:

   npm list @astrojs/cloudflare
   

3. For Astro 6, ensure v13+:

   npm install @astrojs/cloudflare@beta
   

"Too many files for webpack"

Symptoms:

• Build fails with file limit error
• Occurs in large projects

Solution:

The Cloudflare adapter uses Vite, not webpack. If you see this error, check:

1. Ensure adapter is properly configured:

   // astro.config.mjs
   import cloudflare from '@astrojs/cloudflare';
   export default defineConfig({
     adapter: cloudflare(),
   });
   

2. Check for legacy configuration:

   • Remove any @astrojs/vercel or other adapter references
   • Ensure output mode is set correctly

---

Runtime Errors

404 Errors on Specific Routes

Symptoms:

• Some routes return 404 after deployment
• Static assets not found

Solutions:

1. Check _routes.json configuration (for advanced routing):

   {
     "version": 1,
     "include": ["/*"],
     "exclude": ["/api/*"]
   }
   

2. Verify build output:

   npm run build
   ls -la dist/
   

3. Check wrangler.jsonc assets directory:

   {
     "assets": {
       "directory": "./dist",
       "binding": "ASSETS"
     }
   }
   

"env is not defined" or "runtime is not defined"

Symptoms:

• Cannot access Cloudflare bindings in Astro code
• Runtime errors in server components

Solutions:

1. Ensure TypeScript types are configured:

   // src/env.d.ts
   type Runtime = import('@astrojs/cloudflare').Runtime<Env>;
   
   declare namespace App {
     interface Locals extends Runtime {}
   }
   

2. Access bindings correctly:

   ---
   // Correct
   const env = Astro.locals.runtime.env;
   const kv = env.MY_KV_NAMESPACE;
   
   // Incorrect
   const kv = Astro.locals.env.MY_KV_NAMESPACE;
   ---
   

3. Verify platformProxy is enabled:

   // astro.config.mjs
   adapter: cloudflare({
     platformProxy: {
       enabled: true,
     },
   })
   

---

Deployment Issues

"Authentication required" or "Not logged in"

Symptoms:

• wrangler deploy fails with authentication error
• CI/CD deployment fails

Solutions:

1. Authenticate locally:

   npx wrangler login
   

2. For CI/CD, create API token:

   • Go to Cloudflare Dashboard → My Profile → API Tokens
   • Create token with "Edit Cloudflare Workers" template
   • Set as CLOUDFLARE_API_TOKEN in GitHub/GitLab secrets

3. Set account ID:

   # Get account ID
   npx wrangler whoami
   
   # Add to wrangler.jsonc or environment
   export CLOUDFLARE_ACCOUNT_ID=your-account-id
   

"Project name already exists"

Symptoms:

• Deployment fails due to naming conflict

Solutions:

1. Change project name in wrangler.jsonc:

   {
     "name": "my-app-production"
   }
   

2. Or use environments:

   {
     "env": {
       "staging": {
         "name": "my-app-staging"
       }
     }
   }
   

Deployment succeeds but site doesn't update

Symptoms:

• wrangler deploy reports success
• Old version still served

Solutions:

1. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)

2. Verify deployment:

   npx wrangler deployments list
   

3. Check for cached versions:

   npx wrangler versions list
   

4. Force deployment:

   npx wrangler deploy --compatibility-date 2025-01-19
   

---

Performance Issues

Slow initial page load

Symptoms:

• First Contentful Paint (FCP) > 2 seconds
• Large Time to First Byte (TTFB)

Solutions:

1. Use hybrid or static output:

   // Pre-render static pages where possible
   export const prerender = true;
   

2. Enable image optimization:

   adapter: cloudflare({
     imageService: 'compile',
   })
   

3. Cache at edge:

   export async function getStaticPaths() {
     return [{
       params: { id: '1' },
       props: { data: await fetchData() },
     }];
   }
   

High cold start latency

Symptoms:

• First request after inactivity is slow
• Subsequent requests are fast

Solutions:

1. Use mode: 'directory' for better caching:

   adapter: cloudflare({
     mode: 'directory',
   })
   

2. Keep bundle size small - avoid heavy dependencies

3. Use Cloudflare KV for frequently accessed data:

   const cached = await env.KV.get('key');
   if (!cached) {
     const data = await fetch();
     await env.KV.put('key', data, { expirationTtl: 3600 });
   }
   

---

Development Server Issues

Styling not applied in dev mode (Astro 6 Beta)

Symptoms:

• CSS not loading in astro dev
• Works in production but not locally

Status: Known bug in Astro 6 beta

Workarounds:

1. Use production build locally:

   npm run build
   npx wrangler dev --local
   

2. Check GitHub issue for updates:

   • Astro Issue #15194

Cannot test bindings locally

Symptoms:

• Astro.locals.runtime.env is undefined locally
• Cloudflare bindings don't work in dev

Solutions:

1. Ensure platformProxy is enabled:

   adapter: cloudflare({
     platformProxy: {
       enabled: true,
       configPath: './wrangler.jsonc',
     },
   })
   

2. Create .dev.vars for local secrets:

   API_KEY=local_key
   DATABASE_URL=postgresql://localhost:5432/db
   

3. Use remote development:

   npx wrangler dev --remote
   

---

Getting Help

If issues persist:

1. Check official documentation:

   • Astro Cloudflare Guide
   • Cloudflare Workers Docs

2. Search existing issues:

   • Astro GitHub Issues
   • Cloudflare Workers Discussions

3. Join community:

   • Astro Discord
   • Cloudflare Discord