Troubleshooting

Local: server will not start

1. Node version — match .nvmrc (build/scripts/check-node.js enforces).
2. Yarn only — npm triggers force-yarn failure.
3. Port in use — another yarn dev or process on 3001 — stop or change port in dev server config if your branch supports it.

Local: 404 or wrong handler

1. ?debugga=route,config — confirm matched route and merged config.
2. Site prefix — include fn/ (etc.) in the path.
3. Wrong env — yarn dev:stage vs yarn dev changes upstream data; ?env= overrides fetches.

Local: upstream errors / empty payloads

1. ?debugga=source — inspect raw Spark / Brightcove / other responses.
2. Identity — ?debugga=setup:identity for env and URLs.
3. Secrets — some endpoints require AWS or partner secrets only present in deployed envs.

Stale content at CDN

1. Verify route caching policy — see Caching deep dive.
2. Invalidate CDN only when policy change is insufficient — coordinate with infra (invalidation cost).

Build failures

1. yarn lint — fix Biome issues.
2. TypeScript / webpack — read first error in yarn build output; often a bad import or missing file in src/.

Deploy failures

1. Terraform — check GitHub Actions logs for deploy.sh / terraform apply.
2. State lock — DynamoDB lock contention — retry after other apply finishes.

Getting help

• Slack channels per team norm (e.g. #moxie-dev mentioned in legacy setup docs).
• GitHub foxnews/fn-moxie-api issues / PRs with debugga excerpts (redact secrets).

Related

• Debugging
• Moxie runtime API