Vercel Nextjs Debugging

/vercel-nextjs-debugging - Vercel and Next.js MDX Debugging

Activate when a Next.js site deployed on Vercel fails to compile, crashes at runtime, shows truncated error messages, or deploys stale code despite new commits being pushed.

Steps

1. Get the Full Error First

Vercel dashboard UI has character limits for error display. Never debug from a truncated error message. Get the full output via one of these methods, in priority order:

1. Use the get_deployment_build_logs MCP tool for complete output
2. Run vercel logs <deployment-url> via CLI
3. Reproduce the error locally with the same Next.js config

Local reproduction is the most reliable for MDX and build errors because the full stack trace is visible without truncation.

2. MDX Content: Forbidden Syntax

MDX files compiled via next-mdx-remote have two common authoring errors that do not fail at build time but crash at runtime:

HTML Comments (invalid in MDX)

• MDX compiles to JSX; <!-- is treated as an invalid character sequence
• Find: <!-- any text --> Replace with: {/* any text */}
• MDX linters may not catch this until server-side runtime

Import Statements (invalid in next-mdx-remote)

• next-mdx-remote compiles MDX on the server at runtime with no module resolution context
• import statements cause runtime crashes with "Unexpected token" or ___m variable errors
• Fix: remove all import statements from MDX content
• Register components via the components prop on <MDXRemote> in page.tsx instead
• Must register in BOTH blog/[slug]/page.tsx AND backlog/[slug]/page.tsx (separate MDX component registries)

Nested Double Quotes in JSX Attributes (runtime-only error)

• A nested, unescaped double quote inside a JSX string attribute in MDX passes build and lint with no warning at all
• It fails only at runtime in production, crashing to an error boundary (500)
• Fix: use HTML entities (e.g. ") instead of literal nested quotes inside JSX attribute strings

3. Stale Deploy: Code Not Updating

When a Vercel deploy shows old code despite new commits being pushed:

• The build cache is the likely culprit (Vercel aggressively caches build artifacts)
• Fix: uncheck "Build Cache" in project Settings > General, or trigger a clean deploy from the dashboard
• Re-enable the cache after the clean deploy succeeds

4. Cached Error Pages

Vercel's CDN edge caches error pages separately from successful responses. After deploying a fix, the previous error page can persist on the edge:

• Hard-refresh (Cmd+Shift+R) and check in incognito/private browsing before concluding a fix didn't work
• Without this, you're likely viewing a cached error page, not the current deploy

Source Instincts

• mdx-jsx-comments: "when MDX fails to compile with syntax errors near comment-like patterns"
• mdx-no-imports: "when MDX file fails with 'Unexpected token' or '___m' errors at runtime"
• vercel-error-truncation: "when Vercel error message looks incomplete or cuts off mid-sentence"
• vercel-build-cache-stale: "when a Vercel deployment does not reflect recently pushed commits"