Troubleshooting Guide

Common issues and solutions when working with the Sprout platform.

Quick Diagnosis

Service Won't Start

1. Check environment variables:

   doppler secrets

2. Check Docker services:

   docker ps
   docker-compose ps

3. Check logs:

   # Backend
   doppler run -- bun run start:dev
   
   # Docker logs
   docker-compose logs -f

Database Connection Issues

Symptoms: Connection refused, timeout, authentication failed

Solutions:

1. Verify PostgreSQL is running:

   docker ps | grep postgres

2. Check connection string in Doppler:

   doppler secrets get DATABASE_URL

3. Test connection:

   docker exec -it <postgres_container> psql -U postgres -c "SELECT 1"

4. Verify migrations are applied:

   doppler run -- npx prisma migrate status

Redis Connection Issues

Symptoms: Queue not processing, cache not working

Solutions:

1. Verify Redis is running:

   docker ps | grep redis

2. Test Redis connection:

   docker exec -it <redis_container> redis-cli ping

3. Check Redis URL in Doppler:

   doppler secrets get REDIS_URL

Port Already in Use

Symptoms: EADDRINUSE error

Solutions:

1. Find what's using the port:

   lsof -i :3000

2. Kill the process or change port:

   kill -9 <PID>
   # Or change PORT in Doppler

TypeScript Errors

Symptoms: Type errors, compilation failures

Solutions:

1. Regenerate Prisma client:

   bun run postinstall

2. Clear node_modules and reinstall:

   rm -rf node_modules bun.lockb
   bun install

3. Check TypeScript version compatibility

Dependency Issues

Symptoms: Module not found, version conflicts

Solutions:

1. Clear cache and reinstall:

   rm -rf node_modules bun.lockb
   bun install

2. Check for version conflicts:

   bun outdated

3. Verify package.json is correct

Service-Specific Issues

sprout_backend

Worker Not Processing Jobs

1. Check worker is running:

   doppler run -- bun run worker:dev

2. Check Bull Board: http://localhost:3000/queues

3. Check Redis connection

4. Verify queue configuration

API Endpoints Not Working

1. Check server is running:

   curl http://localhost:3000/health

2. Check authentication (if required)

3. Verify CORS configuration

4. Check request logs

sprout_etl

Pipeline Not Running

1. Check ETL service is running:

   curl http://localhost:3001/health

2. Check worker is running:

   doppler run -- bun run worker:dev

3. Verify queue has jobs:

   # Check Redis queue
   docker exec -it <redis_container> redis-cli
   > LLEN bull:etl_queue:wait

Event Matching Failing

1. Check MeiliSearch is accessible:

   curl http://localhost:7700/health

2. Verify events are indexed:

   # Use CLI to check
   doppler run -- bun run cli:dev -- match-events --dry-run --limit 5

3. Check API keys are valid

pricing_dashboard

Build Failing

1. Check TypeScript errors:

   bun run build

2. Check for missing dependencies:

   bun install

3. Clear Vite cache:

   rm -rf node_modules/.vite

API Calls Failing

1. Verify backend is running:

   curl http://localhost:3000/health

2. Check CORS configuration

3. Verify API URL in environment:

   echo $VITE_API_URL

cloudflare-workers

Deployment Failing

1. Check Wrangler configuration:

   bun run check

2. Verify Cloudflare credentials:

   wrangler whoami

3. Check D1 migrations:

   bun run seedLocalD1

Worker Not Triggering

1. Check cron schedule in wrangler.json

2. Verify worker is deployed:

   wrangler deployments list

3. Check worker logs:

   wrangler tail

Common Error Messages

"Cannot find module"

Cause: Missing dependency or incorrect import path

Solution:

bun install
# Check import paths match actual file locations

"Prisma Client not generated"

Cause: Prisma client not generated after schema changes

Solution:

bun run postinstall
# Or manually:
npx prisma generate

"Connection refused"

Cause: Service not running or wrong host/port

Solution:

1. Verify service is running
2. Check connection string
3. Verify network/firewall settings

"Rate limit exceeded"

Cause: Too many API requests

Solution:

1. Check rate limiting configuration
2. Implement backoff/retry logic
3. Reduce request frequency

"Migration failed"

Cause: Database schema conflicts

Solution:

1. Check migration status:

   npx prisma migrate status

2. Resolve conflicts manually if needed

3. Reset database (development only):

   npx prisma migrate reset

Debugging Tips

Enable Debug Logging

Set environment variables:

DEBUG=*
LOG_LEVEL=debug

Use Debugger

1. Start in debug mode:

   doppler run -- bun run start:debug

2. Attach debugger (VS Code):

   • Create .vscode/launch.json
   • Attach to process on port 9229

Check Logs

1. Application logs:

   # Follow logs
   tail -f logs/app.log

2. Docker logs:

   docker-compose logs -f <service>

3. System logs:

   journalctl -u <service> -f

Network Debugging

1. Test connectivity:

   curl -v http://localhost:3000/health
   telnet localhost 5432

2. Check DNS:

   nslookup <hostname>

3. Verify firewall:

   ufw status

Getting Help

1. Check existing documentation
2. Search error messages in codebase
3. Check service logs for detailed errors
4. Review recent changes in git history
5. Ask team members for context

Prevention

1. Always use Doppler for environment variables
2. Run migrations before starting services
3. Check Docker services are running
4. Verify dependencies are installed
5. Test locally before deploying

Next Steps

• Environment Setup - Setup guide
• Docker Setup - Docker troubleshooting
• Testing - Test debugging