TROUBLESHOOTING.md

Troubleshooting Guide

This guide covers common issues you might encounter when setting up or running the Synesthesia development environment, along with their solutions.

Table of Contents

• Development Environment Issues
• Database Issues
• Redis Issues
• Frontend Issues
• Authentication Issues
• Image Upload Issues

Development Environment Issues

The bin/dev script hangs or doesn't start all services

Symptoms:

• The script starts but some services don't appear to be running
• Terminal output stops after starting one or two services

Solutions:

1. Kill any existing processes that might be conflicting:

   pkill -f "rails|puma|redis-server|sidekiq"

2. Ensure ports are available:

   sudo lsof -i :3000  # Rails
   sudo lsof -i :6379  # Redis

3. Clean stale PID files:

   rm -f tmp/pids/*.pid

4. Try the simplified script:

   bin/dev-simple

Issues with Foreman or Process Management

Symptoms:

• Error messages about process management
• "Process exited with status 1" errors

Solutions:

1. Make sure foreman is installed:

   gem install foreman

2. Try running services individually:

   # Terminal 1
   bin/rails s
   
   # Terminal 2
   redis-server tmp/redis.conf
   
   # Terminal 3
   bundle exec sidekiq

Database Issues

Database Connection Failures

Symptoms:

• "PG::ConnectionBad" errors
• "Role 'postgres' does not exist" errors

Solutions:

1. Check PostgreSQL service:

   sudo service postgresql status
   # or
   sudo systemctl status postgresql

2. Start PostgreSQL if needed:

   sudo service postgresql start

3. Verify database.yml configuration:

   cat config/database.yml

4. Create role if missing:

   sudo -u postgres psql -c "CREATE ROLE gburgess WITH LOGIN CREATEDB PASSWORD 'password';"

Migration Errors

Symptoms:

• "Pending Migration Error" messages
• Tables don't exist errors

Solutions:

1. Run migrations:

   bin/rails db:migrate

2. Reset database (warning: destroys data):

   bin/rails db:drop db:create db:migrate db:seed

Redis Issues

Redis Connection Failures

Symptoms:

• "Error connecting to Redis" messages
• ActionCable connection failures

Solutions:

1. Check Redis configuration:

   cat tmp/redis.conf

2. If using Unix socket mode and having issues, switch to TCP: Edit bin/dev-server or use bin/dev-simple which uses TCP mode.

3. Verify Redis is running:

   redis-cli ping

   Should respond with "PONG"

4. Restart Redis:

   redis-cli shutdown
   redis-server tmp/redis.conf

Frontend Issues

JavaScript Build Failures

Symptoms:

• Errors during asset compilation
• Missing JavaScript in browser

Solutions:

1. Check yarn/npm installations:

   yarn --version

2. Clear yarn cache:

   yarn cache clean

3. Reinstall dependencies:

   rm -rf node_modules
   yarn install

4. Check for TypeScript errors:

   yarn type-check

Asset Not Compiling

Symptoms:

• CSS not updating
• JavaScript changes not appearing

Solutions:

1. Manually start asset compilation:

   yarn dev

2. Clear asset cache:

   bin/rails tmp:clear
   rm -rf app/assets/builds/*

Authentication Issues

JWT Authentication Failures

Symptoms:

• "Unauthorized" errors in API responses
• Unable to log in

Solutions:

1. Check browser localStorage for token:

   // In browser console
   localStorage.getItem('token')

2. Verify JWT configuration:

   cat config/initializers/devise.rb

3. Clear JWT denylist:

   bin/rails c
   JwtDenylist.delete_all

Image Upload Issues

Cloudinary Upload Failures

Symptoms:

• Image uploads fail
• Cloudinary errors in logs

Solutions:

1. Check Cloudinary configuration:

   cat config/initializers/cloudinary.rb

2. Verify environment variables:

   cat .env | grep CLOUDINARY

3. Test Cloudinary connection:

   bin/rails c
   Cloudinary::Uploader.upload("app/assets/images/default-avatar.svg")

Active Storage Issues

Symptoms:

• Broken image links
• "ActiveStorage::FileNotFoundError" errors

Solutions:

1. Check storage service configuration:

   cat config/storage.yml

2. Purge problematic attachments:

   bin/rails c
   User.find(1).avatar.purge

3. Reset Active Storage tables:

   bin/rails active_storage:purge:unattached

Still Having Issues?

If you're still experiencing problems after trying these solutions:

1. Check the application logs:

   tail -f log/development.log

2. Run the application in debug mode:

   bin/rails s --debug

3. Try the test environment to verify the core functionality:

   bin/test-environment

4. File an issue on the GitHub repository with detailed error information and steps to reproduce.