Troubleshooting

Common issues and fixes.

Install / dev issues

pnpm install fails with registry error

Check your npm registry: pnpm config get registry. Should be https://registry.npmjs.org/. If you're behind a corporate proxy, set HTTPS_PROXY in your shell.

pnpm dev says "port 3000 already in use"

Another dev server is running. Either kill it (lsof -ti:3000 | xargs kill) or run on a different port:

PORT=3001 pnpm dev

Hot reload stopped working

  • Delete .next/ and restart dev
  • Check your editor isn't saving via an atomic-write that confuses the watcher
  • On macOS, check ulimit -n: if it's under 1024, run ulimit -n 10240 in your shell

Turbopack panic in dev

Rare but happens: Turbopack Error: range start index ... out of range. Fix:

rm -rf .next
pnpm dev

The Turbopack persistence cache got corrupted, usually from mixing pnpm build and pnpm dev in the same .next/.

Build / deploy issues

pnpm build fails with "Module not found"

Check your tsconfig.json path aliases. The starter uses @/* → src/*. If you renamed folders, update both.

Vercel build succeeds but page 404s

Check that the route file has a default export. Next.js App Router requires export default function Page().

OG image returns 404

src/app/opengraph-image.tsx must export a default function and runtime config. If you're in static export mode (output: "export"), next/og is disabled: swap to a static public/og-image.png.

Sitemap is empty or stale

src/app/sitemap.ts is re-evaluated on each request (or build). Check that BLOG_POSTS in src/config/blog.ts is populated and that each post has the slug field.

Style / theme issues

Primary color isn't updating

  1. Check both :root AND .dark blocks in src/app/globals.css: you may have only changed one
  2. Clear your browser cache (CSS chunks have hashed URLs but aggressive caching can bite you)
  3. Verify the @theme inline block at the bottom maps the variable: --color-primary: var(--primary);

Fonts aren't loading

In src/app/layout.tsx, ensure the font CSS variable name matches what globals.css references:

const myFont = SomeFont({
  variable: "--font-my-font",  // ← must match globals.css
});

--font-sans: var(--font-my-font), -apple-system, ...;

Dark mode flash on page load

<html suppressHydrationWarning> must be set (it is, by default). If you added a new top-level script, ensure next-themes loads first.

Content / MDX issues

Blog post 404s

  • Filename (content/blogs/my-post.mdx) must match slug in BLOG_POSTS
  • Entry in src/config/blog.ts is required: the post won't route without it

MDX renders as plain text

Your heading/code/list syntax may be broken. Check:

  • Headings need a space after #
  • Code blocks need triple backticks AND a language tag
  • Lists need a blank line before them

Table doesn't render

You need remark-gfm for pipe-delimited tables. It's enabled by default in [slug]/page.tsx: don't remove it.

SEO issues

Google can't find your site

  1. Check NEXT_PUBLIC_APP_URL matches your production domain
  2. Visit /robots.txt: ensure Allow: / is set and the sitemap URL is correct
  3. Submit the sitemap in Google Search Console
  4. Wait 48-72 hours for initial crawl

OG card looks wrong on social shares

Still stuck?

  • Check the issue exists in a clean clone (pnpm install && pnpm dev)
  • Open an issue in the repo with: exact command run, error output, OS + Node version
  • For template-specific questions: use the support email in your receipt