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

Reproduce and capture the real failure (status, error, request id, time).
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).
Locate the failing service/line from the evidence, not a guess.
Fix the real cause. Don't add logging-only "fixes" and call it done.
For intentional lab/ephemeral config (test secrets, fail-open), don't raise false alarms — leave required env in place.

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.

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.

Treat a failed frozen install as a deployment blocker even if invoking Next directly builds successfully. For ERR_PNPM_IGNORED_BUILDS, inspect the exact dependency lifecycle scripts and the tracked pnpm-workspace.yaml; pnpm may generate ignored placeholder decisions locally. Commit explicit reviewed version-scoped allow/deny decisions, keep strict checking enabled for unknown versions, and verify the normal frozen-install/build path before redeploying.