runtime-debug

Runtime Debug

When something breaks at runtime (a URL 500s, a deploy is down, an ephemeral env misbehaves), look at what actually happened before editing code.

Steps

1. Reproduce and capture the real failure (status, error, request id, time).
2. Check observability first: logs, traces, metrics. Use an observability MCP (e.g. Datadog) if one is available/connected; otherwise fall back to the platform's log stream (CI job, container, Jenkins, cloud logs).
3. Locate the failing service/line from the evidence, not a guess.
4. Fix the real cause. Don't add logging-only "fixes" and call it done.
5. For intentional lab/ephemeral config (test secrets, fail-open), don't raise false alarms — leave required env in place.

MR local preview

• For a requested local link, start the actual worktree app against existing Docker datastores; do not substitute a screenshot gallery. Check Docker Desktop and existing containers first, then use the worktree's Node 18.20.4 and explicit NODE_ENV=local / NODE_PATH. Verify /200 and the requested page separately: a healthy server can still return 404 when Mongo has no CMS content.
• Inspect local CMS collection counts before attempting a restore. An empty Atlas Local container needs sanitized seed data; inspect cached archives and download size before starting a large refresh, especially on constrained connections. Never reset or reseed existing data just to start the server.

Research preview latency

• Separate middleware TTFB from image/render timing before changing public pages. In the portal app, a local preview with unconfigured Upstash Redis can spend seconds retrying rate-limit calls even when the page itself is static.
• Reuse the existing Docker Redis and serverless-redis-http services and their mapped ports. Verify the HTTP pipeline and then the page's rate-limit headers after reconnecting the preview; never bypass production limiting to make a local timing look fast.
• Use headed Chrome when Vercel's preview checkpoint rejects curl/headless requests. Attribute third-party preview-toolbar exceptions by their stack URL rather than hiding all page errors. Compare an exact artwork element crop for reduced-motion proof; full screenshots include animated preview chrome.