Troubleshooting Guide

This document covers common issues, errors, and their solutions when working at Innox Technologies

Table of Contents

• Development Issues

• Build Errors

• TypeScript Errors

• Chakra UI v3 Issues

• Authentication Issues

• Performance Issues

• Deployment Issues

• Getting Help

Development Issues

Issue: "Module not found: Can't resolve '@/components/...'"

Symptoms:

• Import errors for components

• TypeScript errors even though files exist

• Build fails with module resolution errors

Solutions:

1. Check tsconfig.json paths:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

1. Restart TypeScript Server:

   • VS Code: Command Palette → "TypeScript: Restart TS Server"

   • Or restart VS Code entirely

2. Clean and reinstall:

rm -rf node_modules package-lock.json
npm install

Issue: Changes not reflecting in dev server

Symptoms:

• Code changes don't appear in browser

• Hard refresh doesn't work

• Old code still running

Solutions:

1. Restart dev server:

# Stop server (Ctrl+C)
npm run dev

1. Clear .next cache:

rm -rf .next
npm run dev

1. Check for turbopack issues:

# Try without turbopack
npm run dev -- --no-turbopack

Issue: Port 3000 already in use

Symptoms:

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

Solutions:

1. Kill process on port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Or find and kill manually
lsof -i:3000
kill -9 <PID>

1. Use different port:

npm run dev -- -p 3001

Build Errors

Issue: "ReferenceError: document is not defined"

Symptoms:

• Build fails with document/window undefined

• Error during server-side rendering

Cause: Using browser APIs in Server Component

Solution:

// ❌ Bad - Browser API in Server Component
export default function Page() {
  useEffect(() => {
    document.title = "Dashboard";
  }, []);
  return <div>Dashboard</div>;
}

// ✅ Good - Client Component with "use client"
"use client";
export default function Page() {
  useEffect(() => {
    document.title = "Dashboard";
  }, []);
  return <div>Dashboard</div>;
}

Issue: "Server actions cannot be used in Client Components"

Symptoms:

Error: Server actions cannot be used in Client Components

Solution:

// ❌ Bad - Importing Server Action in Client Component without proper setup
"use client";
import { getUser } from "@/app/actions/users"; // This works

// ✅ Good - Server Actions CAN be imported in Client Components
"use client";
import { getUser } from "@/app/actions/users";

export function UserButton({ userId }: { userId: string }) {
  const handleClick = async () => {
    const result = await getUser(userId); // This is fine
  };
  return <button onClick={handleClick}>Get User</button>;
}

Issue: "Module not found: Package subpaths not defined"

Symptoms:

Error: Node.js built-in module 'xyz' is not defined

Solution: Check Next.js version and package.json exports

# Update Next.js
npm install next@latest

TypeScript Errors

Issue: "Property 'X' does not exist on type 'Y'"

Symptoms:

• TypeScript errors on Chakra UI components

• Type mismatches

Solution for Chakra UI v3:

// ❌ Bad - v2 syntax
import { useColorMode } from "@chakra-ui/react";

// ✅ Good - v3 may not have this, use alternative
// Check actual exports in node_modules/@chakra-ui/react

Issue: "Type 'X' is not assignable to type 'Y'"

Symptoms:

• Type errors on props

• Variant/colorPalette errors

Solution:

// Use type assertion or proper typing
import type { ComponentProps } from "react";

interface ButtonProps {
  variant?: "primary" | "secondary";
  colorPalette?: ComponentProps<typeof ChakraButton>["colorPalette"];
}

Issue: "Cannot find module 'next-auth'"

Symptoms:

• Import errors for next-auth

• Type errors

Solution:

# Install next-auth
npm install next-auth

# Check imports for v5
import { auth } from "@/lib/auth/config";
import { signIn } from "next-auth/react";

Chakra UI v3 Issues

Issue: "Property 'Provider' does not exist"

Symptoms:

Error: Property 'Provider' does not exist on type typeof chakra

Cause: Chakra UI v3 has different exports

Solution:

// ❌ Bad - v2 syntax
import { Provider, system } from "@chakra-ui/react";

// ✅ Good - v3 syntax
import { ChakraProvider, defaultSystem } from "@chakra-ui/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ChakraProvider value={defaultSystem}>
      {children}
    </ChakraProvider>
  );
}

Issue: "Property 'Avatar' does not exist"

Symptoms:

• Avatar component not found

• Switch component not found

Cause: These components don't exist in Chakra UI v3

Solution:

// ✅ Good - Custom avatar with Box
<Box
  width="40px"
  height="40px"
  borderRadius="full"
  bg="brand.warmGold"
  display="flex"
  alignItems="center"
  justifyContent="center"
>
  {user?.name?.charAt(0)}
</Box>

// ✅ Good - Toggle with Button
<Button
  variant="ghost"
  onClick={() => setEnabled(!enabled)}
>
  {enabled ? "On" : "Off"}
</Button>

Issue: "Property 'bgPalette' does not exist"

Symptoms:

• Props like bgPalette not recognized

• fallbackSrc not working

Solution:

// ❌ Bad - Old prop names
<Box bgPalette="blue">
  <Image fallbackSrc="/placeholder.png" />
</Box>

// ✅ Good - New prop names
<Box colorPalette="blue">
  <Image /> {/* Remove fallbackSrc */}
</Box>

Issue: How to check available Chakra v3 exports

Solution:

# Check actual exports
cat node_modules/@chakra-ui/react/dist/esm/index.js

# Or in code
import * as Chakra from "@chakra-ui/react";
console.log(Object.keys(Chakra));

Authentication Issues

Issue: "Invalid next-auth config"

Symptoms:

• Auth not working

• Login fails silently

Solutions:

1. Check environment variables:

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

1. Generate NEXTAUTH_SECRET:

openssl rand -base64 32

1. Check auth config:

// src/lib/auth/config.ts
export const authConfig: NextAuthConfig = {
  providers: [
    Credentials({
      credentials: {
        email: { label: "Email", type: "email" },
        password: { label: "Password", type: "password" },
      },
      authorize: async (credentials) => {
        // Check implementation
      },
    }),
  ],
};

Issue: "Session is always null"

Symptoms:

• Session undefined in Server Components

• useSession returns null

Solutions:

1. Check middleware:

// src/middleware.ts
export default auth((req) => {
  // Ensure middleware is properly configured
});

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};

1. Check session usage:

// Server-side
import { auth } from "@/lib/auth/config";
const session = await auth();

// Client-side
import { useSession } from "next-auth/react";
const { data: session } = useSession();

Issue: "Redirect not working after logout"

Symptoms:

• Stays on same page after logout

• Doesn't redirect to login

Solution:

// ✅ Good - Explicit callbackUrl
await signOut({ callbackUrl: "/login" });

Issue: "JWT token not including role"

Symptoms:

• Session doesn't have user role

• Role checks fail

Solution:

// src/lib/auth/config.ts
callbacks: {
  async jwt({ token, user }) {
    if (user) {
      token.id = user.id;
      token.role = (user as any).role; // Ensure role is added
    }
    return token;
  },
  async session({ session, token }) {
    if (token && session.user) {
      session.user.id = token.id as string;
      session.user.role = token.role as UserRole;
    }
    return session;
  },
}

Performance Issues

Issue: Slow initial page load

Diagnosis:

# Check bundle size
npm run build

# Look for large pages in build output

Solutions:

1. Use Server Components by default

2. Lazy load heavy components:

const HeavyChart = dynamic(() => import("@/components/HeavyChart"), {
  ssr: false,
});

1. Optimize images:

import { Image } from "next/image";

<Image src="/logo.png" alt="Logo" width={200} height={40} />

Issue: Too many Client Components

Symptoms:

• Large JavaScript bundle

• Slow client-side hydration

Solution:

// ✅ Good - Server Component with data fetching
export default async function Page() {
  const data = await fetchData();
  return <View data={data} />;
}

// ❌ Bad - Client Component with fetch
"use client";
export default function Page() {
  const [data, setData] = useState(null);
  useEffect(() => {
    fetchData().then(setData);
  }, []);
  return <View data={data} />;
}

Issue: Slow Server Actions

Diagnosis:

// Add logging
export async function slowAction() {
  console.time("slowAction");
  // ... action code
  console.timeEnd("slowAction");
}

Solutions:

1. Parallelize independent operations:

const [users, stats] = await Promise.all([
  getUsers(),
  getStats(),
]);

1. Add database indexes (when using DB)

2. Cache results where appropriate

Deployment Issues

Issue: Build fails on Vercel

Symptoms:

• Works locally, fails on Vercel

• Type errors in production build

Solutions:

1. Check TypeScript version:

{
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

1. Ensure all env vars are set:

• Go to Vercel project settings

• Add NEXTAUTH_URL and NEXTAUTH_SECRET

1. Check build logs:

# Build locally first
npm run build

# Try to reproduce error

Issue: "NEXTAUTH_URL mismatch"

Symptoms:

• Auth fails in production

• Redirect loops

Solution:

# Production .env
NEXTAUTH_URL=https://your-domain.com

# Or let NextAuth auto-detect
# Remove NEXTAUTH_URL in production

Issue: Static generation fails

Symptoms:

• Pages not generating statically

• Build timeout

Solution:

// Use dynamic rendering for authenticated pages
export const dynamic = "force-dynamic";

// Or use revalidation
export const revalidate = 3600; // 1 hour

Debugging Tips

Enable Debug Mode

NextAuth:

NEXTAUTH_DEBUG=true

Next.js:

NODE_OPTIONS='--inspect' npm run dev

Check Server Action Logs

export async function debugAction() {
  console.log("Action called");
  console.log("Session:", await auth());
  // ... rest of action
}

Network Tab

1. Open Chrome DevTools

2. Go to Network tab

3. Filter by "fetch"

4. Look for Server Action calls

5. Check request/response payloads

React DevTools

1. Install React DevTools extension

2. Check component props

3. Look for unnecessary re-renders

4. Verify Server vs Client Components

Common Mistakes

1. Forgetting "use client"

// ❌ Bad - Missing "use client" for interactive component
export function Button() {
  const [count, setCount] = useState(0); // Error!
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

// ✅ Good - Added "use client"
"use client";
export function Button() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

2. Using fetch in Server Components

// ❌ Bad - Client-side fetch in Server Component
export default async function Page() {
  const res = await fetch("https://api.example.com/data"); // This is actually fine in Server Components!
  return <div>{JSON.stringify(data)}</div>;
}

// ✅ Actually Good - fetch IS allowed in Server Components
export default async function Page() {
  const res = await fetch("https://api.example.com/data");
  const data = await res.json();
  return <div>{JSON.stringify(data)}</div>;
}

3. Not handling ActionResult

// ❌ Bad - Not checking success
const result = await deleteUser(userId);
console.log(result.data); // Might be undefined!

// ✅ Good - Check success first
const result = await deleteUser(userId);
if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error);
}

4. Hardcoding colors

// ❌ Bad - Hardcoded color
<Box bg="#F8F9FC">Content</Box>

// ✅ Good - Semantic token
<Box bg="bg.subtle">Content</Box>

Getting Help

1. Check Documentation

• ONBOARDING.md - Setup and development

• ARCHITECTURE.md - System design

• CODE_PATTERNS.md - Coding conventions

2. Search Existing Issues

Before creating new issues, search:

• GitHub issues

• Internal documentation

• Stack Overflow

3. Debug Steps

1. Reproduce the issue consistently

2. Isolate the problem - create minimal reproduction

3. Check console logs - browser and terminal

4. Check network tab - failed requests

5. Try clean build:

   rm -rf .next node_modules
   npm install
   npm run dev

4. Ask for Help

When asking for help, provide:

• What you tried: Steps you took

• Expected behavior: What should happen

• Actual behavior: What actually happened

• Error messages: Full error stack traces

• Environment: Node version, OS, browser

• Code sample: Minimal reproduction

5. Create Issue

Include in your issue:

• Clear title

• Description

• Steps to reproduce

• Expected vs actual behavior

• Screenshots (if applicable)

• Code snippets

• Environment details

Quick Reference

Reset Everything

# Clean slate
rm -rf .next node_modules package-lock.json
npm install
npm run dev

Check Versions

node --version  # Should be 18.17+
npm --version   # Should be 9.0+

Useful Commands

# Type check
npx tsc --noEmit

# Lint
npm run lint

# Build
npm run build

# Start production
npm run start

Environment Check

# List env vars (Unix)
env | grep NEXTAUTH

# Check .env.local exists
ls -la .env.local

---

Still stuck? Reach out to the team or create an issue with details about your problem.