0Days
0Hours
0Min
0Sec
New Release Flash Sale Offer70% OFFGet Now
Get All Access

Troubleshooting Common Issues

This guide helps you resolve common issues you might encounter while working with Next Web Templates.

Installation Issues

Node.js Version Compatibility

Problem: Build fails with Node.js version errors

Solution:

# Check your Node.js version
node --version

# Install Node.js 18+ (recommended)
# Using nvm (recommended)
nvm install 18
nvm use 18

# Or download from nodejs.org

Package Installation Failures

Problem: npm install or yarn install fails

Solutions:

  1. Clear cache and reinstall:

    # For npm
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

# For yarn
yarn cache clean
rm -rf node_modules yarn.lock
yarn install

  2. Use legacy peer deps (if needed):

    npm install --legacy-peer-deps

  3. Check for conflicting global packages:

    npm list -g --depth=0

Permission Errors

Problem: EACCES permission errors during installation

Solution:

# Fix npm permissions (macOS/Linux)
sudo chown -R $(whoami) ~/.npm

# Or use a Node version manager like nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Development Server Issues

Port Already in Use

Problem: Error: listen EADDRINUSE: address already in use :::3000

Solutions:

  1. Kill process using port 3000:

    # Find process using port 3000
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

  2. Use a different port:

    npm run dev -- -p 3001
# or
PORT=3001 npm run dev

Hot Reload Not Working

Problem: Changes not reflecting in browser

Solutions:

  1. Check file watching limits (Linux):

    echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

  2. Disable browser cache:

    • Open DevTools (F12)
    • Go to Network tab
    • Check "Disable cache"

  3. Restart development server:

    # Stop server (Ctrl+C) and restart
npm run dev

Memory Issues

Problem: JavaScript heap out of memory

Solution:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm run dev

# Or add to package.json scripts
"dev": "NODE_OPTIONS='--max-old-space-size=4096' next dev"

Build Issues

TypeScript Errors

Problem: Build fails with TypeScript errors

Solutions:

  1. Check TypeScript configuration:

    // tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

  2. Fix common TypeScript issues:

    // Add proper types for props
interface Props {
  title: string;
  children: React.ReactNode;
}

// Use proper event types
const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
  // ...
}

// Type API responses
interface ApiResponse {
  data: any[];
  message: string;
}

Import/Export Errors

Problem: Module not found or import errors

Solutions:

  1. Check file extensions:

    // Correct
import Component from "./Component";
import { utils } from "../lib/utils";

// Avoid
import Component from "./Component.tsx";

  2. Use absolute imports:

    // Configure in tsconfig.json
"baseUrl": ".",
"paths": {
  "@/components/*": ["components/*"],
  "@/lib/*": ["lib/*"]
}

// Then use
import Button from '@/components/Button'

CSS/Styling Issues

Problem: Styles not loading or conflicting

Solutions:

  1. Check Tailwind CSS configuration:

    // tailwind.config.js
module.exports = {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

  2. Import global styles correctly:

    // app/layout.tsx or pages/_app.tsx
import "./globals.css";

  3. CSS Module naming:

    // Use .module.css for CSS modules
import styles from './Component.module.css'

// Apply classes
<div className={styles.container}>

Runtime Errors

Hydration Mismatch

Problem: Text content does not match server-rendered HTML

Solutions:

  1. Use useEffect for client-only code:

    import { useEffect, useState } from "react";

export default function Component() {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) {
    return null; // or loading state
  }

  return <div>{/* client-only content */}</div>;
}

  2. Use dynamic imports with ssr: false:

    import dynamic from "next/dynamic";

const ClientOnlyComponent = dynamic(() => import("./ClientOnlyComponent"), {
  ssr: false,
});

API Route Errors

Problem: API routes returning 404 or 500 errors

Solutions:

  1. Check file structure:

    pages/api/
├── users/
│   ├── index.ts        # /api/users
│   └── [id].ts         # /api/users/[id]
└── auth/
    └── [...nextauth].ts # /api/auth/*

  2. Proper error handling:

    // pages/api/example.ts
import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  try {
    if (req.method !== 'POST') {
      return res.status(405).json({ error: 'Method not allowed' })
    }

    // Your logic here
    res.status(200).json({ success: true })
  } catch (error) {
    console.error('API Error:', error)
    res.status(500).json({ error: 'Internal server error' })
  }
}

Environment Variables

Problem: Environment variables not working

Solutions:

  1. Check file naming:

    # Correct files
.env.local          # Local development
.env.development    # Development environment
.env.production     # Production environment

  2. Client-side variables:

    # .env.local
# Server-side only
DATABASE_URL=your-database-url

# Client-side (must have NEXT_PUBLIC_ prefix)
NEXT_PUBLIC_API_URL=https://api.example.com

  3. Restart development server after changes:

    # Stop server (Ctrl+C) and restart
npm run dev

Database Issues

Prisma Connection Errors

Problem: Database connection failures

Solutions:

  1. Check DATABASE_URL format:

    # PostgreSQL
DATABASE_URL="postgresql://username:password@localhost:5432/database"

# MySQL
DATABASE_URL="mysql://username:password@localhost:3306/database"

  2. Generate Prisma client:

    npx prisma generate
npx prisma db push

  3. Reset database (development only):

    npx prisma migrate reset
npx prisma db seed

Migration Issues

Problem: Prisma migration failures

Solutions:

  1. Check migration status:

    npx prisma migrate status

  2. Resolve migration conflicts:

    # Mark migration as applied
npx prisma migrate resolve --applied "migration-name"

# Or reset and recreate
npx prisma migrate reset
npx prisma migrate dev

Authentication Issues

NextAuth.js Problems

Problem: Authentication not working

Solutions:

  1. Check environment variables:

    # .env.local
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key

# Provider credentials
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

  2. Verify provider configuration:

    // pages/api/auth/[...nextauth].ts
import NextAuth from 'next-auth'
import GoogleProvider from 'next-auth/providers/google'

export default NextAuth({
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  callbacks: {
    async redirect({ url, baseUrl }) {
      return url.startsWith(baseUrl) ? url : baseUrl
    },
  },
})

Performance Issues

Slow Page Loads

Problem: Pages loading slowly

Solutions:

  1. Optimize images:

    import Image from "next/image";

<Image
  src="/image.jpg"
  alt="Description"
  width={500}
  height={300}
  priority // For above-the-fold images
/>;

  2. Use dynamic imports:

    const HeavyComponent = dynamic(() => import("./HeavyComponent"), {
  loading: () => <p>Loading...</p>,
});

  3. Implement caching:

    // API route with caching
export default function handler(req, res) {
  res.setHeader("Cache-Control", "s-maxage=60, stale-while-revalidate");
  // Your logic
}

Bundle Size Issues

Problem: Large bundle sizes

Solutions:

  1. Analyze bundle:

    npm install --save-dev @next/bundle-analyzer

    // next.config.js
const withBundleAnalyzer = require("@next/bundle-analyzer")({
  enabled: process.env.ANALYZE === "true",
});

module.exports = withBundleAnalyzer({
  // your config
});

    ANALYZE=true npm run build

  2. Tree shake unused code:

    // Import only what you need
import { debounce } from "lodash/debounce";
// Instead of
import _ from "lodash";

Deployment Issues

Vercel Deployment Failures

Problem: Build fails on Vercel

Solutions:

  1. Check build logs:

    • Go to Vercel dashboard
    • Click on failed deployment
    • Review build logs

  2. Environment variables:

    • Add all required environment variables in Vercel dashboard
    • Ensure NEXTAUTH_URL is set to your domain

  3. Build command:

    // package.json
{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}

Static Export Issues

Problem: Static export fails

Solutions:

  1. Configure for static export:

    // next.config.js
const nextConfig = {
  output: "export",
  trailingSlash: true,
  images: {
    unoptimized: true,
  },
};

  2. Remove server-side features:

    • API routes
    • Server-side rendering
    • Incremental static regeneration

Getting Additional Help

Debug Information

When seeking help, provide:

  1. System information:

    node --version
npm --version
npx next --version

  2. Error messages:

    • Full error stack trace
    • Browser console errors
    • Build logs

  3. Reproduction steps:

    • Minimal code example
    • Steps to reproduce the issue

Support Channels

Emergency Fixes

When production is broken and you need to act fast, follow these focused steps to reduce user impact and restore service safely.

1. Immediate containment

  • Put the site in maintenance mode or serve a simple static page to all users while you investigate.
  • Pause any noisy background jobs, cron tasks, or deploys to stop further damage.

Example (static maintenance page via Vercel / hosting redirect or simple nginx rule):

# serve maintenance.html for all requests
location / {
   root /var/www/maintenance;
   try_files /maintenance.html =503;
}

2. Quick rollback (preferred if recent deploy caused the issue)

  • Revert the offending commit and push a rollback:
git revert HEAD
git push origin main
# Trigger your CI/CD to deploy the reverted commit
  • Or deploy a known-good tag:
git checkout tags/v1.2.3
git push origin HEAD:main

3. Hotfix branch (if rollback isn’t possible)

  • Create a minimal hotfix branch, test, and deploy:
git checkout -b hotfix/quick-fix
# make minimal change
git commit -am "hotfix: <short description>"
git push origin hotfix/quick-fix
# trigger CI/CD to deploy hotfix

4. Temporary mitigations

  • Disable problematic features with feature flags or environment variables.
  • Scale horizontally (increase replicas) or vertically (bigger instance) to relieve load.
  • Disable third-party integrations (payment gateways, analytics) that may cause failures.

Example: set an env var to disable a feature and restart:

export FEATURE_X_ENABLED=false
# redeploy or restart service

5. Restart services & clear caches

  • Restart app processes, workers, or containers:
# systemd
sudo systemctl restart my-app

# Docker
docker restart my-app
  • Clear CDN and application caches:
# example: purge CDN via curl to provider API
curl -X POST "https://api.cdn.example/purge" -H "Authorization: Bearer $TOKEN" -d '{"paths":["/*"]}'

6. Database safety

  • If writes are corrupting data, switch DB to read-only (if supported) and failover to a replica.
  • Avoid destructive operations until you have backups. Restore from backups only with a verified plan.

7. Capture diagnostics

  • Collect logs, metrics, and traces before restarting or scaling (rotate if huge).
  • Grab process dumps or heap snapshots for memory issues.
  • Save the exact failing request and stack trace for reproduction.

Commands:

# tail logs
journalctl -u my-app -n 500 --no-pager

# export recent logs to file
journalctl -u my-app -n 2000 > /tmp/my-app-logs.txt

8. Communication checklist

  • Notify on-call, engineering lead, and stakeholders immediately (channel, severity, ETA).
  • Post a short status update to users (status page / social channels) with an estimated time to resolution.
  • Keep updates regular and factual (what, impact, mitigation, next steps).

9. Verify and close

  • After deploying a fix, verify with smoke tests and synthetic transactions before marking resolved.
  • Re-enable paused jobs and features gradually, monitoring for regressions.

10. Post-incident actions

  • Perform a postmortem: timeline, root cause, corrective actions, and owners.
  • Remove temporary mitigations and replace with permanent fixes, tests, and alerts to prevent recurrence.

Use the simplest effective action first (rollback or disable), collect evidence for diagnosis, and follow up with permanent fixes and a postmortem.

11. Monitor deployment:

  • Check application logs
  • Monitor error rates
  • Verify functionality

Remember: When in doubt, start with the simplest solution and work your way up to more complex fixes. Most issues have simple causes!

If you can't find a solution here, please contact our support team.

Previous
Deployment
Next
Tips and Thoughts

Copyright © 2026 Next web templates | nextwebtemplates.com, All rights reserved.

Terms & ConditionsPrivacy PolicyFAQs