Velat.

Troubleshooting

Solutions to common problems when running or deploying Velat.

Installation problems

"node is not recognized"

Node.js is not installed, or you didn't restart your computer after installing it.

Fix:

1. Uninstall Node.js from your system

2. Download the LTS version from https://nodejs.org

3. Install it

4. Restart your computer

5. Verify with node --version

"npm: command not found"

Same cause as above. npm comes with Node.js — if npm is missing, Node.js wasn't installed correctly.

Fix: Reinstall Node.js and restart.

"npm install" fails with `ERESOLVE`

A dependency conflict.

Fix:

rmdir /s /q node_modules
del package-lock.json
npm install

If it still fails:

npm install --legacy-peer-deps

`npm install` takes forever

Normal on first install. Expect 1–3 minutes on a good connection, up to 10 minutes on slow connections.

Do not interrupt it. Let it finish.

Development server problems

"Port 3000 is already in use"

Another application is using port 3000.

Fix A — close the other app:

Check if you have another terminal running npm run dev. Stop it with Ctrl + C.

Fix B — change the port:

Open package.json and change:

"dev": "next dev -p 3001"

Then open http://localhost:3001.

The page is blank

Fix:

1. Stop the server (Ctrl + C)

2. Delete the .next folder:

Windows:

rmdir /s /q .next

macOS / Linux:

rm -rf .next

3. Run npm run dev again

Page shows "404 Not Found"

The route doesn't exist. Check:

  • ―The URL matches your folder structure in app/
  • ―The file is named page.tsx (not page.ts or index.tsx)

Hot reload doesn't work

Sometimes Next.js's file watcher misses changes.

Fix:

1. Save the file again

2. If that doesn't work, stop and restart the server

"Module not found" errors

Fix:

rmdir /s /q node_modules
rmdir /s /q .next
del package-lock.json
npm install
npm run dev

Build problems

"useSearchParams() should be wrapped in a suspense boundary"

Next.js 16 requires useSearchParams() to be wrapped in <Suspense>.

Fix:

Wrap the component that uses useSearchParams():

import { Suspense } from "react";

export default function Page() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <ComponentThatUsesSearchParams />
    </Suspense>
  );
}

"The default export is not a React Component"

The file doesn't export a React component as the default.

Fix:

Check the file. The default export must return JSX:

export default function MyPage() {
  return <div>Hello</div>;
}

If the file uses "use client", generateMetadata and generateStaticParams are not allowed in the same file. Split them:

  • ―page.tsx → Server Component with metadata
  • ―client-component.tsx → Client Component with hooks

Build fails with TypeScript errors

Fix:

Run the linter to see exact errors:

npx tsc --noEmit

Fix them one by one.

"generateStaticParams returns empty array"

Next.js 16 does not allow generateStaticParams to return an empty array.

Fix:

Either return at least one item, or remove the function entirely (which disables static generation for that route).

Content problems

Blog post doesn't appear

Check:

  • ―File is inside data/blog/
  • ―File ends with .md
  • ―Frontmatter opens with ` and closes with `
  • ―title and date fields are present

Product doesn't appear

Same as above, but check data/products/.

Required fields: title, price, category, description, shortDesc, features.

Image doesn't load

If using a remote URL (Unsplash, etc.):

The domain must be whitelisted in next.config.js:

images: {
  remotePatterns: [
    { protocol: "https", hostname: "images.unsplash.com", pathname: "/**" }
  ]
}

Restart the server after editing next.config.js.

If using a local path:

  • ―File must be inside public/images/
  • ―Path must start with /images/ (no public)

Correct: /images/banner.avif

Wrong: public/images/banner.avif

Markdown renders as plain text

Some syntax isn't supported by the built-in parser:

  • ―Tables (| col | col |)
  • ―Nested lists
  • ―Horizontal rules (``)
  • ―Images inside body (![alt](url))

Fix: Use a full Markdown library. Install:

npm install react-markdown remark-gfm

Replace <MarkdownView> with <ReactMarkdown>.

YAML parsing error

Special characters in frontmatter break YAML.

Fix: Wrap values in quotes:

title: "My Post: A Story"

Especially if the value contains :, ", ', [, ], {, }.

Deployment problems

Vercel build fails but local build works

Usually a missing environment variable.

Fix:

1. Vercel project → Settings → Environment Variables

2. Add every variable from your local .env.local

3. Redeploy — env changes don't apply to existing deployments

Vercel shows 404 on all routes

The framework preset is wrong.

Fix:

1. Vercel project → Settings → General

2. Framework Preset: Next.js

3. Redeploy

Netlify build succeeds but site is broken

The Next.js adapter is missing or outdated.

Fix:

1. Netlify project → Plugins

2. Ensure @netlify/plugin-nextjs is installed

3. If pinned to an old version, unpin it

4. Redeploy

Cloudflare Pages shows "nodejs_compat" error

The compatibility flag is missing.

Fix:

1. Cloudflare Pages project → Settings → Functions

2. Compatibility Flags

3. Add nodejs_compat for both Production and Preview

4. Set Compatibility Date to 2022-11-30 or later

5. Redeploy

Custom domain shows "not found"

DNS isn't propagated yet.

Fix:

1. Check that DNS records point to your hosting provider

2. Wait up to 48 hours (usually under 1 hour)

3. Use https://dnschecker.org to verify propagation

Site loads but images are broken in production

next/image requires configuration in next.config.js for remote domains.

Fix:

Add the domain to remotePatterns:

images: {
  remotePatterns: [
    { protocol: "https", hostname: "your-domain.com", pathname: "/**" }
  ]
}

Redeploy.

"next: command not found" on server

Node.js isn't installed or the PATH is wrong on the server.

Fix (VPS):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$HOME/.nvm"
source "$NVM_DIR/nvm.sh"
nvm install 20

Fix (cPanel):

Use cPanel → Setup Node.js App to install Node.js properly. Do not install manually via SSH.

Git problems

"fatal: not a git repository"

You're not inside a Git repository.

Fix:

git init

"Permission denied (publickey)"

SSH key isn't set up.

Fix:

Use HTTPS instead of SSH:

git remote set-url origin https://github.com/YOUR-USERNAME/YOUR-REPO.git

Then push again. Use a Personal Access Token as the password.

"failed to push some refs"

The remote has commits your local branch doesn't have.

Fix:

git pull origin main --rebase
git push origin main

If that fails, force push only if you're sure no one else is working on the repo:

git push origin main --force

Accidentally committed `.env.local`

Fix:

1. Remove from Git:

git rm --cached .env.local

2. Add to .gitignore:

.env.local
.env*.local

3. Commit and push

4. Rotate all secrets that were in that file. Assume they are compromised.

Performance problems

Site feels slow locally

First page load is always slower because Next.js compiles on demand.

Fix: Refresh the page. Subsequent loads are much faster.

Site feels slow in production

Check:

1. Image sizes — large images slow down page load

2. Bundle size — run npm run build and check the output

Fix:

  • ―Use .avif or .webp images instead of .png or .jpg
  • ―Enable next/image (already done if you use <Image>)
  • ―Reduce client components — every "use client" adds to the bundle

Lighthouse score is low

Run Lighthouse in Chrome DevTools:

1. Open your site in Chrome

2. Press F12

3. Go to Lighthouse tab

4. Click Analyze page load

Common fixes:

  • ―Convert images to .avif
  • ―Remove unused dependencies
  • ―Lazy-load below-the-fold content

Still stuck?

If none of these solutions work:

1. Read the full error message — Next.js errors usually point to the exact file and line

2. Search the exact error text on Google or https://stackoverflow.com

3. Check the Next.js docs at https://nextjs.org/docs

4. Copy the error and ask in a community forum

Most problems come from:

  • ―Missing dependencies (npm install)
  • ―Wrong Node.js version (must be 20.9+)
  • ―Stale cache (delete .next folder)
  • ―Missing environment variables