> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tariqdev.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common Sonata installation, build, styling, API, deployment, and licensing issues with fixes.

# Troubleshooting

Use this guide when Sonata does not install, build, render, or deploy as expected.

<Info>
  Start with the first error in the terminal. Later errors are often side effects.
</Info>

## 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:

```bash theme={null}
node -v
pnpm -v
pnpm install
pnpm dev
pnpm build
```

## `pnpm` Is Not Recognized

Install pnpm:

```bash theme={null}
npm install -g pnpm
```

Verify:

```bash theme={null}
pnpm -v
```

## Port Is Already In Use

Use another port:

```bash theme={null}
pnpm dev -- -p 3001
```

## Dependency Install Fails

Try:

```bash theme={null}
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:

```txt theme={null}
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:

```txt theme={null}
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:

```txt theme={null}
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:

```txt theme={null}
app/globals.css
```

Update both `:root` and `html.light` if needed.

## Button Shadows Are Too Strong

Tune:

```css theme={null}
--depth-accent-shadow
--depth-accent-glow
--depth-accent-shadow-stack
--depth-accent-shadow-hover
```

For hero CTAs, check:

```css theme={null}
.hero-cta-soft
```

## Border Beam Is Too Bright

Tune:

```css theme={null}
--border-beam-opacity
--border-beam-blur
--border-beam-size
```

## MDX Does Not Render

Check frontmatter:

```mdx theme={null}
---
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.