Troubleshooting - ZeroStarter

Installation Issues

Dependencies fail to install

If bun install fails, this is usually due to postinstall scripts or cache issues.

Solution 1: Skip postinstall scripts

bun install --ignore-scripts

This bypasses the postinstall hooks that might be causing issues. Solution 2: Clear cache and reinstall

rm -rf node_modules
rm bun.lockb
bun install

Solution 3: Update Bun Ensure you’re using Bun v1.3.0 or later:

bun --version
bun upgrade

After upgrading Bun, restart your terminal to ensure the new version is active.

Module resolution errors

If you see errors about missing modules or path aliases not working: Check TypeScript configuration

bun run check-types

Rebuild all packages

bun run build

Restart your IDE Sometimes TypeScript server needs a restart to pick up changes in monorepo packages.

Database Issues

Cannot connect to PostgreSQL

Database connection errors are often due to incorrect POSTGRES_URL configuration.

Check your connection string format

postgresql://username:password@host:port/database

Common issues:

Missing SSL mode: Some providers require SSL

POSTGRES_URL="postgresql://user:pass@host:5432/db?sslmode=require"

Wrong port: Default is 5432, but some providers use different ports
Firewall blocking: Ensure your IP is whitelisted (especially with cloud providers)

Database doesn’t exist: Create the database first

psql -U postgres -c "CREATE DATABASE your_database;"

Test your connection Try opening Drizzle Studio to verify the connection:

bun run db:studio

If this works, your connection string is correct.

Migration errors

Problem: Migrations fail to apply

Error: relation "users" already exists

Solution:

Check if migrations were already applied:
```
bun run db:studio
```

If tables exist, you may need to reset (⚠️ destroys data):

# Connect to your database
psql $POSTGRES_URL

# Drop all tables
DROP SCHEMA public CASCADE;
CREATE SCHEMA public;

# Re-run migrations
bun run db:migrate

For production, create a new migration:
```
bun run db:generate
```

Never drop tables in production without backing up data first.

Problem: Drizzle Kit fails to generate migrations

Error: Cannot find module '@packages/env'

Solution: Build the env package first:

turbo run build --filter=@packages/env
bun run db:generate

Database connection pool exhausted

This occurs when you have too many open connections to the database.

Solution:

Restart your development server
```
# Stop the server (Ctrl+C)
bun dev
```
Check connection limits in your PostgreSQL provider settings
Reduce connection pool size in packages/db/src/index.ts if needed

Development Server Issues

Port already in use

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

Solution 1: Kill the process using the port For frontend (port 3000):

lsof -ti:3000 | xargs kill -9

For backend (port 4000):

lsof -ti:4000 | xargs kill -9

Solution 2: Change the port In web/next/package.json:

{
  "scripts": {
    "dev": "next dev -p 3001"
  }
}

In api/hono/src/index.ts, update the port configuration.

Hot reload not working

Sometimes file watching doesn’t work properly, especially on Linux or in Docker.

Solution 1: Check file watcher limits (Linux)

# 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

Solution 2: Restart development server

# Stop server (Ctrl+C)
bun dev

Solution 3: Clear Next.js cache

rm -rf web/next/.next
bun dev

Turborepo cache issues

If changes aren’t reflected or builds are stale:

# Clear Turbo cache
rm -rf .turbo
rm -rf node_modules/.cache

# Clean all build artifacts
bun run clean

# Reinstall and rebuild
bun install
bun run build

Type Safety Issues

Frontend doesn’t recognize API types

This usually means the backend AppType isn’t being exported or the backend needs to be built.

Solution 1: Build the backend

turbo run build --filter=@api/hono

Solution 2: Verify AppType export Check api/hono/src/index.ts:

// Make sure this is exported
export type AppType = typeof app

Solution 3: Restart TypeScript server In VS Code: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server” Solution 4: Check the client import In web/next/src/lib/api/client.ts:

import type { AppType } from '@api/hono'

Ensure the import path is correct and the package is in workspace dependencies.

Zod validation errors

ZodError: Invalid input

Debug validation errors:

try {
  const data = schema.parse(input)
} catch (error) {
  if (error instanceof z.ZodError) {
    console.log(JSON.stringify(error.errors, null, 2))
  }
}

Common issues:

Required fields missing: Check all required fields are provided
Type mismatch: Ensure data types match schema (string vs number)
Date formats: Use ISO strings for dates
Nested objects: Validate nested structure matches schema

Authentication Issues

OAuth callback errors

Problem: “Redirect URI mismatch”

The callback URL in your OAuth app must exactly match the one in Better Auth.

For GitHub:

Callback URL: http://localhost:4000/api/auth/callback/github
For production: https://your-api-domain.com/api/auth/callback/github

For Google:

Callback URL: http://localhost:4000/api/auth/callback/google
For production: https://your-api-domain.com/api/auth/callback/google

Check your .env file:

HONO_APP_URL=http://localhost:4000  # Must match OAuth app settings

Session not persisting

Problem: User gets logged out on page refresh Solution 1: Check BETTER_AUTH_SECRET

# Generate a new secret if needed
openssl rand -base64 32

Add to .env:

BETTER_AUTH_SECRET=your-generated-secret

Solution 2: Check cookie settings Ensure HONO_TRUSTED_ORIGINS includes your frontend URL:

HONO_TRUSTED_ORIGINS=http://localhost:3000

Solution 3: Clear browser cookies Sometimes old cookies cause issues. Clear cookies and try again.

CORS errors during authentication

Access to fetch at 'http://localhost:4000/api/auth/signin' has been blocked by CORS policy

Solution: Ensure HONO_TRUSTED_ORIGINS is set correctly in .env:

HONO_TRUSTED_ORIGINS=http://localhost:3000,http://localhost:3001

For production, add your production domain:

HONO_TRUSTED_ORIGINS=https://yourdomain.com,https://www.yourdomain.com

Build & Deployment Issues

Build fails with type errors

bun run build
# Error: Type 'X' is not assignable to type 'Y'

Solution:

Check types locally first:
```
bun run check-types
```

Build packages in order:

turbo run build --filter=@packages/env
turbo run build --filter=@packages/db
turbo run build --filter=@packages/auth
turbo run build

Clear build cache:
```
bun run clean
bun run build
```

Vercel deployment fails

Problem: Build succeeds locally but fails on Vercel

Ensure all environment variables are set in Vercel dashboard.

Checklist:

✅ All .env variables added to Vercel
✅ Build command is correct: bun run build
✅ Output directory is correct: web/next/.next (for Next.js)
✅ Node version matches (use engines in package.json)
✅ Database is accessible from Vercel (check IP whitelist)

Common Vercel issues:

Missing build command: Set to cd ../.. && bun install && bun run build
Wrong root directory: Set to web/next for frontend, api/hono for backend
Environment variables: Must be set for each deployment (preview and production)

Docker build fails

Problem: Docker image won’t build

docker compose up
# Error: Cannot find module...

Solution:

Rebuild without cache:

docker compose build --no-cache
docker compose up

Check .dockerignore: Ensure node_modules and build artifacts are ignored

Verify Docker Compose version:

docker compose version
# Should be v2.x or higher

Performance Issues

Slow initial load

First load in development is always slower due to compilation. Production builds are optimized.

For development:

Enable Turbopack (experimental): In web/next/package.json:

{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

Reduce hot reload scope: Only run the package you’re working on:
```
bun --cwd web/next dev
```

For production: Build and test production bundle:

bun run build
bun run start

Production builds are significantly faster.

High memory usage

During development: This is normal with Turborepo running multiple packages. You can:

Run individual packages:

# Only frontend
bun --cwd web/next dev

# Only backend
bun --cwd api/hono dev

Increase Node memory limit:

NODE_OPTIONS="--max-old-space-size=4096" bun dev

During build: If builds run out of memory:

NODE_OPTIONS="--max-old-space-size=4096" bun run build

IDE & Editor Issues

VS Code doesn’t recognize path aliases

Problem: Imports using @/ or @packages/ show errors Solution:

Ensure TypeScript is using workspace version:
- Open any .ts file
- Click TypeScript version in status bar
- Select “Use Workspace Version”
Restart TS Server: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server”

Check tsconfig.json paths:

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

ESLint/Oxlint errors

Problem: Linting fails or shows incorrect errors Solution:

Run linter:
```
bun run lint
```
Fix auto-fixable issues:
```
bun run format
```
Check Oxlint config: Configuration is in oxlint.json at the root

Still Having Issues?

Check FAQ

Review frequently asked questions for quick answers.

Open an Issue

Report bugs or ask for help on GitHub.

Review Documentation

Check the full documentation for detailed guides.

Follow Updates

Follow @nrjdalal on X for updates and tips.

When reporting issues, include:

Your operating system
Bun version (bun --version)
Node version (node --version)
Error messages (full stack trace)
Steps to reproduce

Resources

​Installation Issues

​Dependencies fail to install

​Module resolution errors

​Database Issues

​Cannot connect to PostgreSQL

​Migration errors

​Database connection pool exhausted

​Development Server Issues

​Port already in use

​Hot reload not working

​Turborepo cache issues

​Type Safety Issues

​Frontend doesn’t recognize API types

​Zod validation errors

​Authentication Issues

​OAuth callback errors

​Session not persisting

​CORS errors during authentication

​Build & Deployment Issues

​Build fails with type errors

​Vercel deployment fails

​Docker build fails

​Performance Issues

​Slow initial load

​High memory usage

​IDE & Editor Issues

​VS Code doesn’t recognize path aliases

​ESLint/Oxlint errors

​Still Having Issues?

Check FAQ

Open an Issue

Review Documentation

Follow Updates

Installation Issues

Dependencies fail to install

Module resolution errors

Database Issues

Cannot connect to PostgreSQL

Migration errors

Database connection pool exhausted

Development Server Issues

Port already in use

Hot reload not working

Turborepo cache issues

Type Safety Issues

Frontend doesn’t recognize API types

Zod validation errors

Authentication Issues

OAuth callback errors

Session not persisting

CORS errors during authentication

Build & Deployment Issues

Build fails with type errors

Vercel deployment fails

Docker build fails

Performance Issues

Slow initial load

High memory usage

IDE & Editor Issues

VS Code doesn’t recognize path aliases

ESLint/Oxlint errors

Still Having Issues?