Troubleshoot

Things will go wrong. The fixes here cover the common cases. When in doubt, paste the error into Claude Code and ask what’s happening — most of these can be solved interactively.

My deploy failed

Wrangler prints the error inline. Read the last 10 lines.

• Project not found — you typed the project name wrong, or the project hasn’t been created yet. Run wrangler pages project create megmude-site --production-branch=main first.
• Authentication error — your wrangler login expired. Run wrangler login again.
• Build failed before deploy — the deploy command runs npm run build first. Read the build error. Most often it’s a TypeScript error or a missing import. Paste it to Claude Code and ask for a fix.

My preview URL shows a 404

• The path doesn’t exist. Astro’s content routes only exist for files in content/articles/. If you typed a URL by hand, double-check the slug.
• The deploy hasn’t finished. Wait ~30 seconds and refresh. Wrangler reports completion before Cloudflare’s edge has fully propagated.

An agent got stuck mid-spawn

If chapter 04’s variant spawn produced fewer branches than you asked for, ask Claude:

Show me the output from the variant agents. Which ones failed? For each failure, tell me what to do — retry that agent, fix and retry, or skip.

If you want to retry a single variant, ask:

Re-run just the variant <branch-name> with the same prompt. Build, push, and deploy.

I broke main

Two flavors:

The site is live but looks wrong. Roll back to the last good commit:

git log --oneline -10

Find the SHA of the last good commit. Then:

git reset --hard <sha> && git push --force origin main

Force-pushing to main is destructive — only do it when you’re certain. Then redeploy:

npm run build && wrangler pages deploy dist --project-name=megmude-site --branch=main --commit-dirty=true

The site won’t deploy at all. Roll back the same way, then redeploy. If you don’t know which commit broke it, ask Claude:

Show me git log --oneline -10. The last good commit was approximately <when>. Help me identify which commit broke production and roll back to the one before.

You can also roll back via the Cloudflare dashboard — Workers & Pages → megmude-site → Deployments → find an earlier successful deployment → Rollback to this deployment. This bypasses the rebuild entirely.

Claude Code can’t see Nexus-Council

Run inside Claude Code:

List the available MCP servers and their status.

If nexus-council isn’t there, the config is wrong. Re-check ~/.claude.json against the snippet in chapter 00 step 7. Quit and restart Claude Code.

If it’s there but errors when called, the API key is missing or wrong:

security find-generic-password -s mcp-nexus-council -a meg -w

If this prints nothing or errors, re-run the security add-generic-password command from chapter 00 step 7 with a fresh key from Thomas.

Build works locally but fails on Cloudflare

Almost always a Node version mismatch. Check what your local is using:

node --version

Cloudflare Pages uses a default Node version that may differ. To pin it, add a NODE_VERSION environment variable in the Cloudflare dashboard for the megmude-site project, set to the version you’re running locally (e.g. 24).

I can’t see megmude.com in Cloudflare

Tell Thomas. Don’t try to fix this yourself — it means your Cloudflare member access isn’t configured correctly, and Thomas has to adjust it on his side.

I want to start over

Worst case, nuke and restart:

git checkout main && git pull origin main && git branch | grep -v '^\*' | grep -v 'main' | xargs -n 1 git branch -D 2>/dev/null

This puts you back on a clean main with no leftover variant branches. Origin still has them; clean those with:

git fetch --prune && git branch -r | grep variant/ | sed 's|origin/||' | xargs -I {} git push origin --delete {}

If your local checkout is somehow corrupt, delete the folder and re-clone:

cd ~/Code && rm -rf megmude-site && gh repo clone <your-username>/megmude-site && cd megmude-site && npm install

Your content is safe on GitHub.