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
pnpm 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 v24 or later.

# 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
pnpm exec turbo clean

# Force rebuild without cache
pnpm exec 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 ../..
pnpm run 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
pnpm run dev                       # Start all apps
pnpm exec turbo clean                   # Clear build cache
pnpm run test                      # Run all tests
pnpm 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