# Vercel Nextjs Debugging

> Debugging patterns for Next.js MDX content and Vercel deployment failures

- Skill: `chris2ao/vercel-nextjs-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chris2ao/vercel-nextjs-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chris2ao/vercel-nextjs-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: chris2ao (https://skillmd.com/u/chris2ao)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chris2ao/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. `&quot;`) 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"