C3 Troubleshooting
Deployment Issues
Placeholder IDs
Error: "Invalid namespace ID"
Fix: Replace placeholders in wrangler.jsonc with real IDs:
npx wrangler kv namespace create MY_KV # Get real IDAuthentication
Error: "Not authenticated"
Fix: npx wrangler login or set CLOUDFLARE_API_TOKEN
Name Conflict
Error: "Worker already exists"
Fix: Change name in wrangler.jsonc
Platform Selection
| Need | Platform |
|---|---|
| Git integration, branch previews | --platform=pages |
| Durable Objects, D1, Queues | Workers (default) |
Wrong platform? Recreate with correct --platform flag.
TypeScript Issues
"Cannot find name 'KVNamespace'"
npm run cf-typegen # Regenerate types
# Restart TS server in editorMissing types after config change: Re-run npm run cf-typegen
Package Manager
Multiple lockfiles causing issues:
rm pnpm-lock.yaml # If using npm
rm package-lock.json # If using pnpmCI/CD
CI hangs on prompts:
npm create cloudflare@latest my-app -- \
--type=hello-world --lang=ts --no-git --no-deployAuth in CI:
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}Framework-Specific
| Framework | Issue | Fix |
|---|---|---|
| Next.js | create-next-app failed | npm cache clean --force, retry |
| Astro | Adapter missing | Install @astrojs/cloudflare |
| Remix | Module errors | Update @remix-run/cloudflare* |
Compatibility Date
"Feature X requires compatibility_date >= ..."
Fix: Update compatibility_date in wrangler.jsonc to today's date
Node.js Version
"Node.js version not supported"
Fix: Install Node.js 18+ (nvm install 20)
Quick Reference
| Error | Cause | Fix |
|---|---|---|
| Invalid namespace ID | Placeholder binding | Create resource, update config |
| Not authenticated | No login | npx wrangler login |
| Cannot find KVNamespace | Missing types | npm run cf-typegen |
| Worker already exists | Name conflict | Change name |
| CI hangs | Missing flags | Add --type, --lang, --no-deploy |
| Template not found | Bad name | Check cloudflare/templates |