Troubleshooting

This guide covers common issues you might encounter while developing with Jubiloop and their solutions.

Common Issues

Husky Hook Issues

If git hooks aren't running when you commit:

# Re-install Husky hooks
npm run prepare

# Ensure pre-commit hook is executable
chmod +x .husky/pre-commit

If you need to bypass hooks for a specific commit:

git commit -m "Your message" --no-verify

Port Conflicts

Jubiloop uses several ports for different services. If you encounter port conflicts:

Default Ports

• Frontend (React): 3000
• Backend (AdonisJS): 3333
• Marketing (Next.js): 3001
• PostgreSQL: 5433
• Redis: 6379
• Caddy: 80, 443

Check What's Using Ports

# Check specific ports
lsof -i :3000   # Frontend
lsof -i :3333   # Backend
lsof -i :3001   # Marketing
lsof -i :5433   # PostgreSQL
lsof -i :6379   # Redis

Solutions

1. Stop conflicting services:

   # Kill process using a port (replace PID with actual process ID)
   kill -9 <PID>

2. Change port numbers in configuration files:

   • Frontend: apps/webapp/package.json or vite.config.js
   • Backend: apps/server/.env
   • Marketing: apps/marketing/package.json
   • Infrastructure: infra/local_dev/docker-compose.yml

Node Version Issues

Jubiloop requires Node.js v22 or later (LTS version).

# Check current version
node --version

# Using nvm to switch versions
nvm install 22
nvm use 22

# Set default version
nvm alias default 22

Turborepo Cache Issues

If you experience unexpected build behavior or stale outputs:

# Clear Turborepo cache
npx turbo clean

# Force rebuild without cache
npx turbo build --force

Docker Container Issues

Database Connection Failures

# Check if containers are running
cd infra/local_dev
docker compose ps

# Restart specific services
docker compose restart postgres redis

# View logs for errors
docker compose logs postgres
docker compose logs redis
docker compose logs caddy

Reset All Data (Warning: This will delete all local data)

cd infra/local_dev
docker compose down -v
docker compose up -d

# Re-run migrations after reset
cd ../..
npm run migration:run

Application Not Accessible via HTTPS

If applications show connection errors when accessing via Caddy:

1. Ensure Apps Listen on All Interfaces

Your applications must listen on 0.0.0.0 (not just localhost):

• Vite (React app): Check vite.config.js has:

  server: {
    host: '0.0.0.0'
  }

• AdonisJS: Your .env should have:

  HOST=0.0.0.0

2. Verify Applications Are Running

# Check if apps are actually running
lsof -i :3000   # Should show your React app
lsof -i :3333   # Should show AdonisJS
lsof -i :3001   # Should show Next.js

3. Regenerate HTTPS Certificates

cd infra/local_dev
./setup-https.sh
docker compose restart caddy

Build Failures

Missing Dependencies

# Clean install all dependencies
rm -rf node_modules package-lock.json
rm -rf apps/*/node_modules packages/*/node_modules
npm install

TypeScript Errors

# Check TypeScript configuration
npx tsc --noEmit

# Build specific package to isolate issues
npx turbo build --filter=webapp

Database Migration Issues

Migration Fails

# Check database connection
cd infra/local_dev
docker compose exec postgres psql -U postgres -c '\l'

# Reset migrations (Warning: Deletes all data)
cd apps/server
node ace migration:rollback --batch=0
node ace migration:run

Seeding Fails

# Run seeds with verbose output
cd apps/server
node ace db:seed --debug

Getting Help

If you're still experiencing issues:

1. Check logs for detailed error messages
2. Search existing issues in the project repository
3. Create a new issue with:
   • Description of the problem
   • Steps to reproduce
   • Error messages/logs
   • Your environment (OS, Node version, etc.)

Useful Commands Summary

# Infrastructure
cd infra/local_dev
docker compose up -d              # Start all services
docker compose logs -f            # View all logs
docker compose restart <service>  # Restart specific service
docker compose down -v            # Stop and remove everything

# Development
npm run dev                       # Start all apps
npx turbo clean                   # Clear build cache
npm run test                      # Run all tests
npm run migration:run             # Run database migrations

# Debugging
lsof -i :<port>                   # Check port usage
node --version                    # Check Node version
docker --version                  # Check Docker version

---

Previous: Local Development Setup