Skip to main content

​
Troubleshooting

Use this guide when Sonata does not install, build, render, or deploy as expected.
Start with the first error in the terminal. Later errors are often side effects.

​
Quick Checklist

  1. Check Node.js version.
  2. Check pnpm version.
  3. Reinstall dependencies.
  4. Check .env.local.
  5. Restart the dev server.
  6. Read terminal logs.
  7. Read browser console logs.
  8. Run a production build.
Commands: 
node -v
pnpm -v
pnpm install
pnpm dev
pnpm build

​
pnpm Is Not Recognized

Install pnpm: 
npm install -g pnpm
Verify: 
pnpm -v

​
Port Is Already In Use

Use another port: 
pnpm dev -- -p 3001

​
Dependency Install Fails

Try: 
pnpm install
If it still fails:
  • Delete node_modules.
  • Keep the lockfile unless update instructions say otherwise.
  • Confirm Node.js 20 or newer.
  • Confirm network access to the npm registry.
  • Check whether a package version was changed manually.

​
Blank Page

Check:
  • Terminal logs.
  • Browser console.
  • Missing environment variables.
  • Import errors.
  • Client component errors.
  • Invalid data in config files.
  • Hydration mismatches.
  • Build errors.

​
404 Page After Deployment

Check:
  • The route exists under app/.
  • The deployment built the latest commit.
  • The hosting platform is using Next.js.
  • Links use the correct path.
  • File and folder casing matches exactly.

​
Hydration Mismatch

Common causes:
  • Date.now() rendered directly in JSX.
  • Math.random() rendered directly in JSX.
  • window or document used outside useEffect.
  • Theme state differs between server and client.
Move browser-only logic into useEffect.

​
Build Fails

Read the first real error. Common causes:
  • TypeScript error.
  • Invalid import.
  • Missing file.
  • Client component missing "use client".
  • Invalid MDX syntax.
  • Missing environment variable.
  • Case-sensitive path issue on Linux deployments.

​
TypeScript Error After Editing Data

Common causes:
  • Missing required field.
  • Wrong field name.
  • Wrong price or spec type.
  • Duplicate ID where a unique ID is expected.
  • A plan was added to the wrong tier shape.
Compare your new item with an existing working item in the same data file.

​
Product Cards Do Not Update

Check the correct data file: 
lib/data/game-hosting.ts
lib/data/product-config.ts
Game hosting uses game-hosting.ts. Non-game product pages mostly use product-config.ts.

​
Billing URL Is Wrong

Check: 
lib/config/site.ts
lib/data/game-hosting.ts
lib/data/product-config.ts
Most URLs use siteConfig.billing.url plus a product path. Also check:
  • The billing base URL has the correct domain.
  • Product suffix matches the billing panel route.
  • Query parameters match the provider.
  • Selected billing cycle is passed correctly.

​
Domain Lookup Fails

Domain lookup uses: 
app/api/domain-check/route.ts
Possible causes:
  • RDAP endpoint is unavailable.
  • TLD has no public RDAP endpoint.
  • Registry rate limit.
  • Deployment platform blocks outbound requests.
  • Domain is premium or reserved.

​
Stock Shows Unavailable

Check:
  • PTERODACTYL_PANEL_URL
  • PTERODACTYL_APP_KEY
  • API key permissions.
  • Pterodactyl location IDs.
  • Node and allocation state.
  • API logs.

​
Status Page Does Not Load

Check:
  • UPTIMEROBOT_API_KEY
  • UptimeRobot monitors.
  • API route logs.
  • Production environment variables.

​
Colors Look Wrong

Check: 
app/globals.css
Update both :root and html.light if needed.

​
Button Shadows Are Too Strong

Tune: 
--depth-accent-shadow
--depth-accent-glow
--depth-accent-shadow-stack
--depth-accent-shadow-hover
For hero CTAs, check: 
.hero-cta-soft

​
Border Beam Is Too Bright

Tune: 
--border-beam-opacity
--border-beam-blur
--border-beam-size

​
MDX Does Not Render

Check frontmatter: 
---
title: "Page Title"
description: "Short description."

tags: ["Docs"]
readTime: 3
---
Common causes:
  • Invalid frontmatter.
  • Unclosed JSX tag.
  • Broken Markdown table.
  • Raw < or > outside code blocks.
  • Component not registered in MDX renderer.

​
Deployment Fails

Check:
  • Build command.
  • Start command.
  • Node.js version.
  • Environment variables.
  • Case-sensitive file paths.
  • Platform logs.

​
Open Graph Preview Is Wrong

Check:
  • lib/config/site.ts
  • seo.ogImage
  • Image path under public/
  • Production URL.
  • Platform preview cache.
Some apps cache previews. Re-test with a new URL or cache debugger.

​
License Issue

Sonata is under the Sonata Commercial License. Do not:
  • Resell.
  • Redistribute.
  • Leak.
  • Crack.
  • Nulled-release.
  • Remove license markers.
  • Sell modified copies as another template.
Ask Hiddenmy and TariqIsHuman for written permission if you need extended redistribution or white-label rights.