Local Development

Local development issues stem from environment mismatches or missing configuration. Verify pnpm version, workspace dependencies, and environment variables in that order.

Module Not Found Errors

Symptoms: TypeScript compilation fails with Cannot find module '@workspace/auth' or Module not found: @workspace/ui.

Diagnosis: Workspace dependencies not installed or pnpm version mismatch.

Solution:

Clean install all dependencies:

# Remove all node_modules
rm -rf node_modules pnpm-lock.yaml
rm -rf apps/*/node_modules apps/*/.next
rm -rf packages/*/node_modules

# Reinstall with pnpm
pnpm install

Verify pnpm version:

pnpm --version
# Should show 9.12.0 or higher

# Use Corepack to install correct version
corepack enable
corepack prepare pnpm@9.12.0 --activate

Port Already in Use

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

Diagnosis: Another process using port 3000 or 3001.

Solution:

Find and kill process:

# Find process on port 3000
lsof -ti:3000

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

# Or use different port
pnpm dev --port 3002

Environment Variable Not Loading

Symptoms: process.env.VARIABLE_NAME returns undefined.

Diagnosis: Variable not in .env.local or not prefixed with NEXT_PUBLIC_ for client access.

Solution:

Server-side variables (API routes, server components):

BETTER_AUTH_SECRET=your-secret
AUTUMN_SECRET_KEY=your-key

Client-side variables (browser code):

NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-project.convex.site

Restart development server after changing .env.local.

TypeScript Errors in Workspace Packages

Symptoms: TypeScript errors in @workspace/* imports. Red squiggles in IDE.

Diagnosis: Workspace packages not built or TypeScript server stale.

Solution:

Build workspace packages:

# Build all packages
pnpm build

# Or build specific package
pnpm --filter @workspace/ui build

Restart TypeScript server in VS Code: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

Convex Dev Not Connecting

Symptoms: npx convex dev fails to connect or shows authentication errors.

Diagnosis: Not logged into Convex CLI or deployment not configured.

Solution:

Login to Convex:

npx convex login

Initialize deployment if needed:

npx convex dev --configure new
# Follow prompts to create deployment

Hot Reload Not Working

Symptoms: Code changes don't reflect in browser. Must manually refresh.

Diagnosis: Turbopack watch mode issue or file system watcher limit reached.

Solution:

Increase file watchers (Linux/macOS):

# 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

Restart development server with Turbopack:

pnpm dev --turbopack

Build Failing Locally

Symptoms: pnpm build fails with TypeScript errors or module resolution issues.

Diagnosis: Type errors, missing dependencies, or environment variable validation failures.

Solution:

Run validation steps individually to isolate issue:

# Check linting
pnpm lint

# Check types
pnpm typecheck

# Skip env validation if testing
SKIP_ENV_VALIDATION=true pnpm build

Related Documentation

• Installation - Initial setup guide
• Development - Development workflow
• Authentication - Auth-specific troubleshooting