LAB GUIDE / APPENDIX
Troubleshooting
Accounts#
| Problem | Fix |
|---|---|
| Cloudflare signup shows a challenge or error | Wait a minute and retry. Many signups from the same network can trigger extra checks. Tell the teacher if it persists |
| "Verify your email" / deploy fails | Click the link in Cloudflare's verification email, then retry |
Terminal#
| Problem | Fix |
|---|---|
node: command not found (after installing) | Close and reopen the terminal |
npx wrangler login doesn't open a browser | Copy the URL it prints into your browser |
git push asks for a password | Run gh auth login (HTTPS → web browser). GitHub doesn't accept account passwords for git |
git push rejected (fetch first) | git pull --rebase then git push |
wrangler dev asks which account, or fails with an account error | You have several Cloudflare accounts. The AI binding runs remotely in dev, so Wrangler needs to know which one. Set CLOUDFLARE_ACCOUNT_ID to the account you created today (find it in the dashboard sidebar), for example CLOUDFLARE_ACCOUNT_ID=<id> npm run dev on macOS/Linux, or $env:CLOUDFLARE_ACCOUNT_ID="<id>"; npm run dev in PowerShell |
| Port 8787 in use | npx wrangler dev --port 8788 |
Windows curl behaves strangely | Use curl.exe or the PowerShell snippet in section 7 |
Deploys (Workers Builds)#
| Problem | Fix |
|---|---|
| Pushed but nothing changed | Dashboard → your Worker → Deployments: is the build still running? Did it fail? Open the build log |
| Build failed: name mismatch | Don't change "name" in wrangler.jsonc. It must match the Worker name in the dashboard |
Changed a var in the dashboard and it was reset | Expected. vars come from wrangler.jsonc on every deploy |
Runtime#
| Problem | Fix |
|---|---|
| The ID card says "Character: unknown" and your code looks right | SWAPI is down, so getCharacter returned the placeholder. It tries swapi.dev, then swapi.info. Run npx wrangler tail and look for "SWAPI request failed". Wait a minute and reload. Cached answers (cacheTtl) keep working |
CHARACTER_ID is 17 (or above 83) and the card stays "unknown" | That Character doesn't exist. Pick a number from 1 to 83, except 17 |
| Your Droid says it is "Unknown Droid" | Same cause as the line above: getCharacter returned the placeholder. Check npx wrangler tail |
Error: Worker exceeded CPU time limit | Something heavy is running per request. Ask the teacher; the template is designed to stay well under the limit |
| Anything else | npx wrangler tail, then read the error. It's almost always telling you exactly what's wrong |