Troubleshooting | Client Guides

This guide covers solutions to common problems you might encounter during installation, setup, and development. If you're stuck, check here first before asking for help!

ℹ️

Quick Tips

Most issues are solved by restarting the dev server
Check that environment variables are spelled correctly (case-sensitive)
Make sure you're using Node.js 18 or higher
Clear browser cache if you see stale data

Installation Issues

❌ "npm: command not found"

This means Node.js/npm isn't installed or isn't in your PATH.

Solution:

Go to nodejs.org
Download and install Node.js (LTS version)
Close and reopen your terminal
Verify with node --version

❌ "EACCES: permission denied" During npm install

This is a permission error. Don't use sudo!

Solution:

Configure npm to use your home directory for global packages:

bash

1mkdir ~/.npm-global
2npm config set prefix '~/.npm-global'
3echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
4source ~/.bashrc

❌ Port 3000 Already in Use

If you see "Port 3000 is already in use", something else is using that port.

Solution 1:

Stop whatever is using port 3000 (maybe another dev server)

Solution 2:

Use a different port:

bash

1PORT=3001 npm run dev

Then visit http://localhost:3001 instead. Also update AUTH_URL in .env.local to match.

❌ Database Migration Failed

If npm run db:dev fails:

Solution:

Delete the existing database: rm prisma/dev.db
Try again: npm run db:dev
If it still fails, check that the prisma/ folder exists

❌ Page Shows Errors or Won't Load

If the browser shows errors after starting the dev server:

Solution:

Check the terminal for error messages
Try stopping the dev server (Ctrl+C) and restarting: npm run dev
Clear your browser cache and refresh
Make sure you're on http://localhost:3000 (not HTTPS)

❌ Node.js Version Too Old

If your Node.js version is below 18.x:

Solution:

Visit nodejs.org
Download the latest LTS version
Run the installer (it will replace your old version)
Verify with node --version

Environment Variable Issues

❌ "Environment variable not found" Error

If you see this error in the console:

Solution:

Check that .env.local exists in the project root (not in a subdirectory)
Verify the variable name is spelled correctly (they're case-sensitive)
Make sure there are no spaces around the = sign
Restart your dev server after adding/changing variables

❌ Variables Not Loading

If changes to .env.local don't seem to take effect:

Solution:

Stop your dev server completely (Ctrl+C)
Restart with npm run dev
Check the file is named exactly .env.local (not .env.local.txt)
Verify you're editing the file in the project root, not a subfolder

❌ Can't See .env Files in File Explorer

Files starting with a dot are hidden by default on some systems.

Solution:

Use your code editor's file browser, or enable "Show hidden files" in your OS settings.

Windows: File Explorer → View → Show → Hidden items
macOS: Press Cmd+Shift+. in Finder
Linux: Press Ctrl+H in file manager

❌ Can't Generate AUTH_SECRET

If you don't have openssl:

Solution:

Use this website to generate a random secret:

https://generate-secret.vercel.app/32

Authentication Issues

❌ "Configuration Error" When Clicking Sign In

This usually means your environment variables aren't set correctly.

Solution:

Check that .env.local exists in the project root
Verify the variable names match exactly (GITHUB_ID, not GITHUB_CLIENT_ID)
Make sure there are no quotes around the values
Restart your dev server after changing .env.local

❌ "Redirect URI Mismatch" Error

This means the callback URL in your OAuth app doesn't match the one in the code.

Solution:

GitHub: Must be exactly http://localhost:3000/api/auth/callback/github

Google: Must be exactly http://localhost:3000/api/auth/callback/google

Check for typos
Make sure you're using http:// not https://
No trailing slashes
Port must be 3000 (or match your actual port)

❌ "Access Denied" After Authorizing

This can happen if:

Your email isn't verified on GitHub/Google
The OAuth app is in testing mode (Google) and your email isn't added as a test user
Database connection failed - check that npm run db:dev was successful

❌ Sign In Button Doesn't Show Provider

If a provider button is missing from the sign-in page:

Solution:

Check that the environment variables are set (GITHUB_ID or GOOGLE_ID)
The app automatically hides providers that aren't configured
Restart your dev server after adding new variables

General Development Issues

❌ Changes Not Showing in Browser

If you make code changes but don't see them in the browser:

Solution:

Wait a few seconds for hot reload to apply changes
Hard refresh the browser (Ctrl+Shift+R or Cmd+Shift+R)
Clear browser cache
Restart the dev server if still not working

❌ TypeScript Errors in IDE

Red squiggly lines or type errors in your code editor:

Solution:

Run npm install to ensure all dependencies are installed
Restart your code editor's TypeScript server (VS Code: Cmd/Ctrl+Shift+P → "Restart TS Server")
Check npm run typecheck in terminal for actual errors

❌ "Module not found" Errors

If you see errors about missing modules:

Solution:

Run npm install
Delete node_modules and package-lock.json, then run npm install again
Restart your dev server

❌ Build Fails in Production

If npm run build fails:

Solution:

Read the error message carefully - it usually tells you exactly what's wrong
Run npm run lint to check for code issues
Run npm run typecheck to check for TypeScript errors
Make sure all environment variables required for production are set

React Hydration Errors

❌ "Hydration failed because the server rendered text didn't match the client"

This error occurs when the server and client render different content, often with date formatting. For example, the server might render "12/30/2025" (US format) while the client renders "30/12/2025" (EU format) based on browser locale.

Solution:

This starter kit includes a date formatting utility at src/lib/utils/date.tsthat prevents this issue by using a fixed locale. Use it instead of native toLocaleDateString():

Using the date utility

1import { formatDate, formatDateTime } from "@/lib/utils/date";
2 
3// ✅ Use this (consistent server/client rendering)
4formatDate(new Date());                    // "12/30/2025"
5formatDate(new Date(), { month: 'long' }); // "December 30, 2025"
6formatDateTime(new Date());                // "12/30/2025, 2:30 PM"
7 
8// ❌ Avoid this (causes hydration mismatches)
9new Date().toLocaleDateString();           // Different on server vs client

💡

Customizing Date Format

To change the date format globally (e.g., to European format), edit one line in the utility:

src/lib/utils/date.ts

1// Change from:
2export const DEFAULT_LOCALE = 'en-US';
3 
4// To your preferred locale:
5export const DEFAULT_LOCALE = 'fr-FR';  // French: "30/12/2025"
6export const DEFAULT_LOCALE = 'de-DE';  // German: "30.12.2025"
7export const DEFAULT_LOCALE = 'ja-JP';  // Japanese: "2025/12/30"

All dates in your app will automatically use the new format, and hydration errors will still be prevented because both server and client use the same fixed locale.

❌ Other Hydration Mismatch Errors

Hydration errors can also be caused by:

Using typeof window !== "undefined" checks that create different server/client branches
Using Math.random() or Date.now() during render
Browser extensions that modify the HTML before React loads
Invalid HTML nesting (e.g., div inside p)

Solution:

For browser-only APIs, use Next.js dynamic imports with ssr: false
Move random/time generation into useEffect hooks
Try disabling browser extensions temporarily to test
Check browser console for HTML validation warnings

Still Stuck?

Before Asking for Help

Check the terminal for error messages (read them carefully!)
Search for the exact error message online
Try restarting your dev server and clearing browser cache
Make sure you're following a guide step-by-step without skipping
Verify all environment variables are set correctly

When Asking for Help, Include:

The exact error message (copy-paste, don't paraphrase)
What you were trying to do when the error occurred
What guide you're following
Your Node.js version (node --version)
Your operating system (Windows, macOS, Linux)
What you've already tried to fix it

Related Guides

🚀 Quick Start

Streamlined setup guide to get running fast

Installation

Detailed installation instructions

Environment Variables

Configure your environment variables

Adding OAuth Providers

Configure OAuth providers

Installation Issues

❌ "npm: command not found"

This means Node.js/npm isn't installed or isn't in your PATH.

Solution:

Go to nodejs.org
Download and install Node.js (LTS version)
Close and reopen your terminal
Verify with node --version

❌ "EACCES: permission denied" During npm install

This is a permission error. Don't use sudo!

Solution:

Configure npm to use your home directory for global packages:

bash

1mkdir ~/.npm-global
2npm config set prefix '~/.npm-global'
3echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
4source ~/.bashrc

❌ Port 3000 Already in Use

If you see "Port 3000 is already in use", something else is using that port.

Solution 1:

Stop whatever is using port 3000 (maybe another dev server)

Solution 2:

Use a different port:

bash

1PORT=3001 npm run dev

Then visit http://localhost:3001 instead. Also update AUTH_URL in .env.local to match.

❌ Database Migration Failed

If npm run db:dev fails:

Solution:

Delete the existing database: rm prisma/dev.db
Try again: npm run db:dev
If it still fails, check that the prisma/ folder exists

❌ Page Shows Errors or Won't Load

If the browser shows errors after starting the dev server:

Solution:

Check the terminal for error messages
Try stopping the dev server (Ctrl+C) and restarting: npm run dev
Clear your browser cache and refresh
Make sure you're on http://localhost:3000 (not HTTPS)

❌ Node.js Version Too Old

If your Node.js version is below 18.x:

Solution:

Visit nodejs.org
Download the latest LTS version
Run the installer (it will replace your old version)
Verify with node --version

Environment Variable Issues

❌ "Environment variable not found" Error

If you see this error in the console:

Solution:

Check that .env.local exists in the project root (not in a subdirectory)
Verify the variable name is spelled correctly (they're case-sensitive)
Make sure there are no spaces around the = sign
Restart your dev server after adding/changing variables

❌ Variables Not Loading

If changes to .env.local don't seem to take effect:

Solution:

Stop your dev server completely (Ctrl+C)
Restart with npm run dev
Check the file is named exactly .env.local (not .env.local.txt)
Verify you're editing the file in the project root, not a subfolder

❌ Can't See .env Files in File Explorer

Files starting with a dot are hidden by default on some systems.

Solution:

Use your code editor's file browser, or enable "Show hidden files" in your OS settings.

Windows: File Explorer → View → Show → Hidden items
macOS: Press Cmd+Shift+. in Finder
Linux: Press Ctrl+H in file manager

❌ Can't Generate AUTH_SECRET

If you don't have openssl:

Solution:

Use this website to generate a random secret:

https://generate-secret.vercel.app/32

Authentication Issues

❌ "Configuration Error" When Clicking Sign In

This usually means your environment variables aren't set correctly.

Solution:

Check that .env.local exists in the project root
Verify the variable names match exactly (GITHUB_ID, not GITHUB_CLIENT_ID)
Make sure there are no quotes around the values
Restart your dev server after changing .env.local

❌ "Redirect URI Mismatch" Error

This means the callback URL in your OAuth app doesn't match the one in the code.

Solution:

GitHub: Must be exactly http://localhost:3000/api/auth/callback/github

Google: Must be exactly http://localhost:3000/api/auth/callback/google

Check for typos
Make sure you're using http:// not https://
No trailing slashes
Port must be 3000 (or match your actual port)

❌ "Access Denied" After Authorizing

This can happen if:

Your email isn't verified on GitHub/Google
The OAuth app is in testing mode (Google) and your email isn't added as a test user
Database connection failed - check that npm run db:dev was successful

❌ Sign In Button Doesn't Show Provider

If a provider button is missing from the sign-in page:

Solution:

Check that the environment variables are set (GITHUB_ID or GOOGLE_ID)
The app automatically hides providers that aren't configured
Restart your dev server after adding new variables

General Development Issues

❌ Changes Not Showing in Browser

If you make code changes but don't see them in the browser:

Solution:

Wait a few seconds for hot reload to apply changes
Hard refresh the browser (Ctrl+Shift+R or Cmd+Shift+R)
Clear browser cache
Restart the dev server if still not working

❌ TypeScript Errors in IDE

Red squiggly lines or type errors in your code editor:

Solution:

Run npm install to ensure all dependencies are installed
Restart your code editor's TypeScript server (VS Code: Cmd/Ctrl+Shift+P → "Restart TS Server")
Check npm run typecheck in terminal for actual errors

❌ "Module not found" Errors

If you see errors about missing modules:

Solution:

Run npm install
Delete node_modules and package-lock.json, then run npm install again
Restart your dev server

❌ Build Fails in Production

If npm run build fails:

Solution:

Read the error message carefully - it usually tells you exactly what's wrong
Run npm run lint to check for code issues
Run npm run typecheck to check for TypeScript errors
Make sure all environment variables required for production are set

React Hydration Errors

❌ "Hydration failed because the server rendered text didn't match the client"

Solution:

This starter kit includes a date formatting utility at src/lib/utils/date.tsthat prevents this issue by using a fixed locale. Use it instead of native toLocaleDateString():

Using the date utility

1import { formatDate, formatDateTime } from "@/lib/utils/date";
2 
3// ✅ Use this (consistent server/client rendering)
4formatDate(new Date());                    // "12/30/2025"
5formatDate(new Date(), { month: 'long' }); // "December 30, 2025"
6formatDateTime(new Date());                // "12/30/2025, 2:30 PM"
7 
8// ❌ Avoid this (causes hydration mismatches)
9new Date().toLocaleDateString();           // Different on server vs client

💡

Customizing Date Format

To change the date format globally (e.g., to European format), edit one line in the utility:

src/lib/utils/date.ts

1// Change from:
2export const DEFAULT_LOCALE = 'en-US';
3 
4// To your preferred locale:
5export const DEFAULT_LOCALE = 'fr-FR';  // French: "30/12/2025"
6export const DEFAULT_LOCALE = 'de-DE';  // German: "30.12.2025"
7export const DEFAULT_LOCALE = 'ja-JP';  // Japanese: "2025/12/30"

All dates in your app will automatically use the new format, and hydration errors will still be prevented because both server and client use the same fixed locale.

❌ Other Hydration Mismatch Errors

Hydration errors can also be caused by:

Using typeof window !== "undefined" checks that create different server/client branches
Using Math.random() or Date.now() during render
Browser extensions that modify the HTML before React loads
Invalid HTML nesting (e.g., div inside p)

Solution:

For browser-only APIs, use Next.js dynamic imports with ssr: false
Move random/time generation into useEffect hooks
Try disabling browser extensions temporarily to test
Check browser console for HTML validation warnings

Still Stuck?

Before Asking for Help

Check the terminal for error messages (read them carefully!)
Search for the exact error message online
Try restarting your dev server and clearing browser cache
Make sure you're following a guide step-by-step without skipping
Verify all environment variables are set correctly

When Asking for Help, Include:

The exact error message (copy-paste, don't paraphrase)
What you were trying to do when the error occurred
What guide you're following
Your Node.js version (node --version)
Your operating system (Windows, macOS, Linux)
What you've already tried to fix it