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](#build-errors)
2. [Runtime Errors](#runtime-errors)
3. [Deployment Issues](#deployment-issues)
4. [Performance Issues](#performance-issues)
5. [Development Server Issues](#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`:
   ```jsonc
   {
     "compatibility_flags": ["nodejs_compat"]
   }
   ```

2. **Use React 18** temporarily if the issue persists:
   ```bash
   npm install react@18 react-dom@18
   ```

3. **Check for related GitHub issues:**
   - [Astro Issue #12824](https://github.com/withastro/astro/issues/12824)

### "Cannot find module '@astrojs/cloudflare'"

**Symptoms:**
- Import error in `astro.config.mjs`
- Type errors in TypeScript

**Solutions:**

1. **Install the adapter:**
   ```bash
   npm install @astrojs/cloudflare
   ```

2. **Verify installation:**
   ```bash
   npm list @astrojs/cloudflare
   ```

3. **For Astro 6, ensure v13+:**
   ```bash
   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:**
   ```javascript
   // 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):
   ```json
   {
     "version": 1,
     "include": ["/*"],
     "exclude": ["/api/*"]
   }
   ```

2. **Verify build output:**
   ```bash
   npm run build
   ls -la dist/
   ```

3. **Check wrangler.jsonc assets directory:**
   ```jsonc
   {
     "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:**
   ```typescript
   // src/env.d.ts
   type Runtime = import('@astrojs/cloudflare').Runtime<Env>;

   declare namespace App {
     interface Locals extends Runtime {}
   }
   ```

2. **Access bindings correctly:**
   ```astro
   ---
   // 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:**
   ```javascript
   // 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:**
   ```bash
   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:**
   ```bash
   # 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:**
   ```jsonc
   {
     "name": "my-app-production"
   }
   ```

2. **Or use environments:**
   ```jsonc
   {
     "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:**
   ```bash
   npx wrangler deployments list
   ```

3. **Check for cached versions:**
   ```bash
   npx wrangler versions list
   ```

4. **Force deployment:**
   ```bash
   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:**
   ```javascript
   // Pre-render static pages where possible
   export const prerender = true;
   ```

2. **Enable image optimization:**
   ```javascript
   adapter: cloudflare({
     imageService: 'compile',
   })
   ```

3. **Cache at edge:**
   ```javascript
   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:
   ```javascript
   adapter: cloudflare({
     mode: 'directory',
   })
   ```

2. **Keep bundle size small** - avoid heavy dependencies

3. **Use Cloudflare KV** for frequently accessed data:
   ```javascript
   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:**
   ```bash
   npm run build
   npx wrangler dev --local
   ```

2. **Check GitHub issue for updates:**
   - [Astro Issue #15194](https://github.com/withastro/astro/issues/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:**
   ```javascript
   adapter: cloudflare({
     platformProxy: {
       enabled: true,
       configPath: './wrangler.jsonc',
     },
   })
   ```

2. **Create .dev.vars for local secrets:**
   ```bash
   API_KEY=local_key
   DATABASE_URL=postgresql://localhost:5432/db
   ```

3. **Use remote development:**
   ```bash
   npx wrangler dev --remote
   ```

---

## Getting Help

If issues persist:

1. **Check official documentation:**
   - [Astro Cloudflare Guide](https://docs.astro.build/en/guides/deploy/cloudflare/)
   - [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)

2. **Search existing issues:**
   - [Astro GitHub Issues](https://github.com/withastro/astro/issues)
   - [Cloudflare Workers Discussions](https://github.com/cloudflare/workers-sdk/discussions)

3. **Join community:**
   - [Astro Discord](https://astro.build/chat)
   - [Cloudflare Discord](https://discord.gg/cloudflaredev)