Skip to content

Troubleshooting Guide

Breadcrumbs: Documentation > Guides > Troubleshooting

This guide provides solutions to common issues you may encounter while developing or deploying the portfolio website.

Table of Contents

Development Issues

Issue: Development server won't start

Symptoms:

npm run dev
# Error: Cannot find module 'next'

Solution:

  1. Reinstall dependencies:
rm -rf node_modules package-lock.json
npm install
  1. Clear Next.js cache:
rm -rf .next
npm run dev
  1. Check Node.js version:
node --version
# Should be v20 or higher

If version is too low, upgrade Node.js:

# Using nvm
nvm install 20
nvm use 20

Issue: Module not found errors

Symptoms:

Module not found: Can't resolve '@/components/ui/button'

Solution:

  1. Check tsconfig.json has correct path aliases:
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}
  1. Restart TypeScript server in VS Code:
  2. Press Cmd/Ctrl + Shift + P
  3. Type "TypeScript: Restart TS Server"

  4. Select and run

  5. Restart development server:

# Stop server (Ctrl+C)
npm run dev

Issue: Hot reload not working

Symptoms:

  • Changes to files don't reflect in browser
  • Must manually refresh to see changes

Solution:

  1. Check file watchers limit (Linux/WSL):
# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Increase limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
  1. Restart development server with Turbopack:
npm run dev
# Uses --turbopack flag by default

  1. Check for TypeScript errors:

  2. Fix any TypeScript errors in the console

  3. Errors can prevent hot reload

Issue: Styles not applying correctly

Symptoms:

  • Tailwind classes not working
  • Components look unstyled
  • Dark mode not working

Solution:

  1. Check Tailwind CSS configuration:
// tailwind.config.ts
content: [
  './pages/**/*.{ts,tsx}',
  './components/**/*.{ts,tsx}',
  './app/**/*.{ts,tsx}',
  './src/**/*.{ts,tsx}',
],
  1. Verify CSS imports:
// app/layout.tsx
import "./globals.css";
  1. Check dark mode configuration:
// tailwind.config.ts
darkMode: 'class',

  1. Clear browser cache:

  2. Open DevTools (F12)

  3. Right-click refresh button

  4. Select "Empty Cache and Hard Reload"

  5. Rebuild Tailwind:

rm -rf .next
npm run dev

Issue: TypeScript errors in components

Symptoms:

Property 'slug' does not exist on type 'Project'

Solution:

  1. Check interface definitions:
// lib/projects.ts
export interface Project {
  slug: string;
  title: string;
  // ... other fields
}
  1. Verify type imports:
import { Project } from "@/lib/projects";
  1. Restart TypeScript server (see above)

Build Issues

Issue: Build fails with TypeScript errors

Symptoms:

npm run build
# Type error: Property 'x' does not exist on type 'Y'

Solution:

  1. Run type checking locally:
npx tsc --noEmit

  1. Fix all type errors - No any workarounds in production

  2. Check for unused imports:

npm run lint

Issue: Build fails with "Out of memory"

Symptoms:

npm run build
# FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

Solution:

  1. Increase Node.js memory:
# package.json
{
  "scripts": {
    "build": "NODE_OPTIONS='--max-old-space-size=4096' next build"
  }
}
  1. Check for circular dependencies:
npm install --save-dev madge
npx madge --circular --extensions ts,tsx .
  1. Optimize imports:
// ❌ BAD: Imports entire library
import { Button } from "@/components/ui";

// ✅ GOOD: Specific import
import { Button } from "@/components/ui/button";

Issue: Build succeeds but pages are blank

Symptoms:

  • npm run build succeeds
  • Deployed site shows blank pages
  • Console shows errors

Solution:

  1. Check environment variables:
# .env.production
NEXT_PUBLIC_SITE_URL="https://your-domain.com"
  1. Check for client-only code in server components:
// ❌ BAD: Using browser APIs in server component
export default function Page() {
  const width = window.innerWidth; // Error!
  return <div>{width}</div>;
}

// ✅ GOOD: Use client component
'use client';

export default function Page() {
  const width = window.innerWidth;
  return <div>{width}</div>;
}

  1. Check console for errors:

  2. Open browser DevTools (F12)

  3. Look for errors in Console tab
  4. Fix any runtime errors

Issue: Static generation fails

Symptoms:

Error: Page "/projects/[slug]" is missing "generateStaticParams()"

Solution:

// app/projects/[slug]/page.tsx
import { getProjects } from "@/lib/projects";

export async function generateStaticParams() {
  const projects = await getProjects();
  return projects.map((project) => ({
    slug: project.slug,
  }));
}

Deployment Issues

Issue: Docker build fails

Symptoms:

docker-compose up website-prod
# Error: failed to solve with frontend dockerfile.v0

Solution:

  1. Check Dockerfile syntax:
FROM node:20-alpine AS base

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

CMD ["npm", "start"]
  1. Check Docker Compose configuration:
version: "3.8"
services:
  website-prod:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
  1. Rebuild without cache:
docker-compose build --no-cache website-prod
docker-compose up website-prod

Issue: Deployed site shows 404 errors

Symptoms:

  • Home page works
  • Other pages show 404

Solution:

  1. Check Next.js output mode:
// next.config.mjs
const nextConfig = {
  output: "standalone", // For Docker deployments
};
  1. Verify file structure in build:
docker-compose exec website-prod ls -la /app/.next/standalone
  1. Check server configuration - Ensure all routes are handled by Next.js

Issue: Environment variables not working

Symptoms:

  • Site loads but features don't work
  • Console shows "undefined" for config values

Solution:

  1. Check variable prefix:
# ✅ GOOD: Available in browser
NEXT_PUBLIC_SITE_URL="https://example.com"

# ❌ BAD: Only available server-side
SITE_URL="https://example.com"
  1. Rebuild after changing environment variables:
npm run build
# or
docker-compose build website-prod
  1. Verify in Docker Compose:
services:
  website-prod:
    environment:
      - NEXT_PUBLIC_SITE_URL=https://example.com
      - NODE_ENV=production

Content Issues

Issue: Project not showing up

Symptoms:

  • Created my-project.json
  • Project doesn't appear on /projects page

Checklist:

  1. File location correct?
content/projects/my-project.json  # ✅ Correct
content/my-project.json          # ❌ Wrong location
  1. Valid JSON?
# Test JSON validity
cat content/projects/my-project.json | jq .
  1. Required fields present?
{
  "title": "Project Title",
  "shortDescription": "Brief description",
  "description": "Long description",
  "technologies": ["Next.js"],
  "images": []
}
  1. Restart development server:
# Stop server (Ctrl+C)
npm run dev

Issue: Project images not displaying

Symptoms:

  • Images show broken icon
  • 404 error in console

Solution:

  1. Check image path:
{
  "images": [
    {
      "src": "/images/projects/my-project/screenshot.jpg",
      "alt": "Screenshot description"
    }
  ]
}
  1. Verify file exists:
ls -la public/images/projects/my-project/
# Should show screenshot.jpg
  1. Check file permissions:
chmod 644 public/images/projects/my-project/*.jpg

  1. Supported formats:

  2. Images: .jpg, .jpeg, .png, .webp, .gif

  3. Videos: .mp4, .webm, .mov

Issue: Project order not working

Symptoms:

  • Set "order": 1 but project appears in wrong position

Solution:

  1. Check order values:
// Featured projects: order 1-6
{
  "order": 1  // Will appear first
}

// Non-featured projects: no order field or order > 6
{
  // No order field - sorted alphabetically
}
  1. Verify in code:
// lib/projects.ts sorts by order, then alphabetically
export async function getProjects(): Promise<Project[]> {
  return projects.sort((a, b) => {
    if (a.order !== undefined && b.order !== undefined) {
      return a.order - b.order;
    }
    // ...
  });
}

Performance Issues

Issue: Slow page loads

Symptoms:

  • Pages take > 3 seconds to load
  • Large JavaScript bundles

Solution:

  1. Analyze bundle size:
npm run build:analyze
  1. Optimize images:
// Use Next.js Image component
import Image from 'next/image';

<Image
  src="/images/profile.jpg"
  alt="Profile"
  width={500}
  height={500}
  priority // For above-the-fold images
/>
  1. Lazy load components:
import dynamic from 'next/dynamic';

const ProjectGallery = dynamic(() => import('@/components/project-gallery'), {
  loading: () => <p>Loading...</p>,
});
  1. Enable caching:
// app/api/route.ts
export async function GET() {
  return new Response(content, {
    headers: {
      "Cache-Control": "public, max-age=86400",
    },
  });
}

Issue: Large bundle size

Symptoms:

  • Build output shows large chunks
  • Slow initial page load

Solution:

  1. Check bundle analyzer:
npm run build:analyze
# Opens browser with bundle visualization
  1. Split large dependencies:
// next.config.mjs
const nextConfig = {
  experimental: {
    optimizePackageImports: ["@radix-ui/react-dialog", "lucide-react"],
  },
};
  1. Remove unused dependencies:
npm uninstall unused-package

SEO Issues

Issue: Sitemap not generating

Symptoms:

  • /sitemap.xml returns 404

Solution:

  1. Check sitemap file exists:
// app/sitemap.ts should exist
export default async function sitemap() {
  // ...
}
  1. Verify build output:
npm run build
# Check for sitemap generation in output
  1. Check deployment:
curl https://your-domain.com/sitemap.xml

Issue: Metadata not appearing

Symptoms:

  • Page title is wrong
  • Description missing in search results

Solution:

  1. Check metadata exports:
// app/page.tsx
import { Metadata } from "next";

export const metadata: Metadata = {
  title: "Page Title",
  description: "Page description",
};

  1. Verify in browser:

  2. View page source (Ctrl+U)

  3. Search for <title> and <meta name="description">

  4. Check template:

// app/layout.tsx
export const metadata: Metadata = {
  title: {
    template: "%s | Software Engineer & AI",
    default: "Simon Stijnen | Software Engineer & AI",
  },
};

Issue: Robots.txt not working

Symptoms:

  • Search engines not crawling site

Solution:

  1. Check robots file:
// app/robots.ts
export default function robots() {
  return {
    rules: {
      userAgent: "*",
      allow: "/",
    },
    sitemap: "https://your-domain.com/sitemap.xml",
  };
}
  1. Test robots.txt:
curl https://your-domain.com/robots.txt

Environment Issues

Issue: .env not loading

Symptoms:

  • Environment variables are undefined

Solution:

  1. Check file name:
ls -la
# Should see .env (not env.txt or .env.txt)
  1. Restart development server:
# Changes to .env require restart
npm run dev
  1. Check variable usage:
// ✅ GOOD: Public variables
const url = process.env.NEXT_PUBLIC_SITE_URL;

// ❌ BAD: Private variables in client components
("use client");
const secret = process.env.SECRET_KEY; // Undefined!

Database/Content Issues

Issue: JSON parsing errors

Symptoms:

Error parsing JSON for project my-project

Solution:

  1. Validate JSON:
cat content/projects/my-project.json | jq .
# Should output formatted JSON or show error
  1. Common JSON mistakes:
// ❌ BAD: Trailing comma
{
  "title": "Project",
  "technologies": ["React"],
}

// ✅ GOOD: No trailing comma
{
  "title": "Project",
  "technologies": ["React"]
}

// ❌ BAD: Single quotes
{
  'title': 'Project'
}

// ✅ GOOD: Double quotes
{
  "title": "Project"
}

  1. Use a JSON validator:

  2. Online: jsonlint.com

  3. Editor: Install JSON validation extension

Getting More Help

If you're still experiencing issues:

  1. Check GitHub Issues:
  2. Search for similar issues

  3. Open a new issue if needed

  4. Enable debug logging:

// next.config.mjs
const nextConfig = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
};
  1. Check Next.js documentation:
  2. Next.js Docs

  3. Next.js Discord

  4. Inspect build output:

npm run build -- --debug

See Also

Next Steps

  • Review common solutions above
  • Check logs for error details
  • Search GitHub issues
  • Open a new issue if problem persists

Last Updated: February 2026
Maintainers: Simon Stijnen
Need Help? Open an issue on GitHub