Troubleshooting

Troubleshooting

Read the first useful error, not the last page of output. If a fix takes longer than two minutes, use the checkpoint recovery lane and keep moving.

Symptom	What it means	Fastest fix
Expected 202, got 404 on main	No agent is mounted yet	Expected; continue to checkpoint 1
fetch failed	The tested URL is unreachable	For Live deploy, confirm npm run deploy succeeded and use its exact URL; for Local dev, start Vite and use its printed URL
Port 5173 is already in use	Strict port selection stopped Vite	Run npm run dev -- --port 5180, then use http://localhost:5180 everywhere
ERR_FILE_NOT_FOUND_IN_OPTIMIZED_DEP_DIR or Cannot find module 'agents' after switching checkpoints	Vite stayed open while the branch or node_modules changed	Stop every workshop Vite process with Ctrl+C, run npm ci on the selected branch, then start npm run dev again
Node 23 or EBADENGINE	The active Node release is unsupported	Run volta install node@24.19.0, reinstall with npm ci, then run npm run check
Workers AI binding warning	AI always uses the remote binding	Keep remote: true; usage is expected
No Cloudflare account selected	The terminal lacks your account ID	Export your own CLOUDFLARE_ACCOUNT_ID using the command in Session setup
Durable Object export error	The generated class is missing from Cloudflare Config	Restore the starter vite.config.ts, then run npm run build
Model fails under flue run	Workers AI is unavailable in that Node runner	Use the checkpoint’s Live deploy smoke tests, or its Local dev tab with Vite
POST returns 202 with no immediate answer	Agent work is asynchronous	Let npm run smoke poll until completion
Wikipedia returns 403	The request lacks a descriptive user agent	Copy src/tools/wikipedia.ts from lab 4
Forecast rejects the date	Open-Meteo forecasts only the near future	Use a date within the next 16 days
Sandbox tools fail to start	Docker is stopped, Containers are unavailable, or SDK/image versions differ	Start Docker, confirm Containers are enabled in the Cloudflare dashboard, and use @cloudflare/sandbox@0.12.10 with image 0.12.10
The first Sandbox dev start seems stuck	Vite is building and starting the container image	Wait for VITE ... ready; the first start can take 30 seconds or longer
First deployed Sandbox requests fail after the Worker URL appears	The container image may still be provisioning	Wait several minutes after the first container deployment, then retry the Sandbox prompt; inspect the deploy error if image build/upload failed
Container application belongs to another Durable Object namespace	A previous workshop run left field-trip-agent-sandbox attached to an older Sandbox namespace	Confirm you are using your own account, then use the facilitator recovery below
Deploy asks for a subdomain	Your account has no registered workers.dev subdomain	Register one in Workers & Pages, then save it in Session setup

Diagnose without guessing

git status --short
git branch --show-current
git rev-parse --short HEAD
node --version
npx wrangler whoami
npm run typecheck

Share those six outputs with a facilitator. Together they answer: what changed, which branch and commit you are on, which runtime you use, which account receives the deploy, and whether the code compiles.

Recover a stale workshop container

Only use this recovery in your own workshop account. List the container applications and find the ID whose name is exactly field-trip-agent-sandbox:

npx wrangler containers list
APPLICATION_ID="paste-the-field-trip-agent-sandbox-application-id"
npx wrangler containers delete "$APPLICATION_ID"
npm run deploy

Do not delete an application with a different name. The next deploy recreates the workshop container against the current Sandbox Durable Object namespace.

Return to a known file

If an error began after an edit, compare the local file with the complete, copyable file in the current lab. Run npm run typecheck before exploring a different fix; workshop failures are often one missing import or stale file.