Getting Started
Environment Setup
Testing
Common Errors and Solutions
Troubleshooting guide for common errors during Chatwoot development setup
Common Errors and Solutions
This guide covers the most common errors encountered during Chatwoot development setup and their solutions. Use this as a quick reference when troubleshooting issues.
Installation and Setup Errors
Ruby and Bundler Issues
Error Message:
An error occurred while installing pg (1.5.4), and Bundler cannot continue.
Make sure that `gem install pg -v '1.5.4'` succeeds before bundling.
Cause: Missing PostgreSQL development headers or incorrect pg_config path.
Solutions:
# Install PostgreSQL with Homebrew
brew install postgresql
# Configure bundle to use correct pg_config
bundle config build.pg --with-pg-config=/opt/homebrew/bin/pg_config
# For Intel Macs
bundle config build.pg --with-pg-config=/usr/local/bin/pg_config
# Retry bundle install
bundle install
# Install PostgreSQL with Homebrew
brew install postgresql
# Configure bundle to use correct pg_config
bundle config build.pg --with-pg-config=/opt/homebrew/bin/pg_config
# For Intel Macs
bundle config build.pg --with-pg-config=/usr/local/bin/pg_config
# Retry bundle install
bundle install
# Install PostgreSQL development headers
sudo apt-get update
sudo apt-get install libpq-dev postgresql-client
# Install build essentials
sudo apt-get install build-essential
# Retry bundle install
bundle install
# Install PostgreSQL development packages
sudo yum install postgresql-devel
# Install development tools
sudo yum groupinstall "Development Tools"
# Retry bundle install
bundle install
Error Message:
Your Ruby version is 3.1.0, but your Gemfile specified 3.3.3
Cause: Wrong Ruby version installed.
Solutions:
# Install correct Ruby version
rbenv install 3.3.3
# Set as global version
rbenv global 3.3.3
# Verify version
ruby --version
# Rehash to update shims
rbenv rehash
# Install correct Ruby version
rbenv install 3.3.3
# Set as global version
rbenv global 3.3.3
# Verify version
ruby --version
# Rehash to update shims
rbenv rehash
# Install correct Ruby version
rvm install 3.3.3
# Use the version
rvm use 3.3.3 --default
# Verify version
ruby --version
# Install correct Ruby version
asdf install ruby 3.3.3
# Set as global version
asdf global ruby 3.3.3
# Verify version
ruby --version
Error Message:
Bundler could not find compatible versions for gem "bundler"
Cause: Incompatible Bundler version.
Solution:
# Check current Bundler version
bundler --version
# Install specific Bundler version (check Gemfile.lock)
gem install bundler:2.4.22
# Update Bundler
gem update bundler
# Clean bundle cache
bundle clean --force
# Retry installation
bundle install
Node.js and Package Manager Issues
Error Message:
error @chatwoot/chatwoot@1.0.0: The engine "node" is incompatible with this module.
Cause: Wrong Node.js version.
Solutions:
# Install correct Node.js version
nvm install 20
# Use the version
nvm use 20
# Set as default
nvm alias default 20
# Verify version
node --version
# Install correct Node.js version
nvm install 20
# Use the version
nvm use 20
# Set as default
nvm alias default 20
# Verify version
node --version
# Install correct Node.js version
n 20
# Verify version
node --version
# Install correct Node.js version
asdf install nodejs 20.10.0
# Set as global version
asdf global nodejs 20.10.0
# Verify version
node --version
Error Message:
pnpm: command not found
Cause: pnpm not installed.
Solutions:
# Install pnpm globally
npm install -g pnpm
# Or using corepack (Node.js 16.10+)
corepack enable
corepack prepare pnpm@latest --activate
# Or using Homebrew (macOS)
brew install pnpm
# Verify installation
pnpm --version
Error Message:
ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies
Cause: Peer dependency conflicts or corrupted cache.
Solutions:
# Clear pnpm cache
pnpm store prune
# Remove node_modules and lock file
rm -rf node_modules pnpm-lock.yaml
# Reinstall with legacy peer deps
pnpm install --legacy-peer-deps
# Or force installation
pnpm install --force
# Alternative: use npm
npm install
Database Errors
PostgreSQL Connection Issues
Error Message:
PG::ConnectionBad: could not connect to server: Connection refused
Cause: PostgreSQL service not running or incorrect connection parameters.
Solutions:
# Check if PostgreSQL is running
brew services list | grep postgresql
# Start PostgreSQL
brew services start postgresql
# Check connection
psql postgres -c "SELECT 1;"
# If user doesn't exist, create it
createuser -s chatwoot
# Check if PostgreSQL is running
brew services list | grep postgresql
# Start PostgreSQL
brew services start postgresql
# Check connection
psql postgres -c "SELECT 1;"
# If user doesn't exist, create it
createuser -s chatwoot
# Check PostgreSQL status
sudo systemctl status postgresql
# Start PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql
# Switch to postgres user and create chatwoot user
sudo -u postgres createuser -s chatwoot
# Set password for chatwoot user
sudo -u postgres psql -c "ALTER USER chatwoot PASSWORD 'password';"
# Start PostgreSQL container
docker run --name postgres-chatwoot \
-e POSTGRES_USER=chatwoot \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=chatwoot_development \
-p 5432:5432 \
-d postgres:15
# Check if container is running
docker ps | grep postgres
Error Message:
ActiveRecord::NoDatabaseError: FATAL: database "chatwoot_development" does not exist
Cause: Database not created.
Solution:
# Create databases
bundle exec rails db:create
# If that fails, create manually
createdb chatwoot_development
createdb chatwoot_test
# Or using psql
psql postgres -c "CREATE DATABASE chatwoot_development;"
psql postgres -c "CREATE DATABASE chatwoot_test;"
Error Message:
ActiveRecord::PendingMigrationError: Migrations are pending
Cause: Database schema is not up to date.
Solutions:
# Run pending migrations
bundle exec rails db:migrate
# If migrations fail, check status
bundle exec rails db:migrate:status
# Reset database (WARNING: destroys data)
bundle exec rails db:drop db:create db:migrate db:seed
# For specific migration issues
bundle exec rails db:migrate:up VERSION=20231201000000
Redis Connection Issues
Error Message:
Redis::CannotConnectError: Error connecting to Redis on localhost:6379
Cause: Redis service not running.
Solutions:
# Check if Redis is running
brew services list | grep redis
# Start Redis
brew services start redis
# Test connection
redis-cli ping
# Check if Redis is running
brew services list | grep redis
# Start Redis
brew services start redis
# Test connection
redis-cli ping
# Check Redis status
sudo systemctl status redis
# Start Redis
sudo systemctl start redis
sudo systemctl enable redis
# Test connection
redis-cli ping
# Start Redis container
docker run --name redis-chatwoot \
-p 6379:6379 \
-d redis:7-alpine
# Test connection
docker exec redis-chatwoot redis-cli ping
Application Runtime Errors
Rails Server Issues
Error Message:
Address already in use - bind(2) for "127.0.0.1" port 3000
Cause: Another process is using port 3000.
Solutions:
# Find process using port 3000
lsof -ti:3000
# Kill the process
kill -9 $(lsof -ti:3000)
# Or use a different port
bundle exec rails server -p 3001
# Check what's running on the port
netstat -tulpn | grep :3000
Error Message:
ArgumentError: Missing `secret_key_base` for 'development' environment
Cause: SECRET_KEY_BASE not set in environment.
Solution:
# Generate a new secret key
bundle exec rails secret
# Add to .env file
echo "SECRET_KEY_BASE=$(bundle exec rails secret)" >> .env
# Or set temporarily
export SECRET_KEY_BASE=$(bundle exec rails secret)
bundle exec rails server
Error Message:
Webpacker::Manifest::MissingEntryError: Webpacker can't find application.js
Cause: Webpack assets not compiled or compilation failed.
Solutions:
# Check if webpack dev server is running
ps aux | grep webpack
# Start webpack dev server
pnpm run dev
# Or compile assets manually
bundle exec rails assets:precompile
# Clear webpack cache
rm -rf tmp/cache/webpacker
rm -rf public/packs
# Reinstall node modules
rm -rf node_modules
pnpm install
Sidekiq Worker Issues
Error Message:
Jobs are queued but not being processed
Cause: Sidekiq worker not running.
Solutions:
# Check if Sidekiq is running
ps aux | grep sidekiq
# Start Sidekiq
bundle exec sidekiq
# Check Sidekiq web interface
open http://localhost:3000/sidekiq
# Clear failed jobs
bundle exec rails runner "Sidekiq::Queue.new.clear"
Error Message:
Redis::CommandError: OOM command not allowed when used memory > 'maxmemory'
Cause: Redis running out of memory.
Solutions:
# Check Redis memory usage
redis-cli info memory
# Clear Redis cache
redis-cli flushall
# Increase Redis memory limit (redis.conf)
# maxmemory 256mb
# Or restart Redis
brew services restart redis # macOS
sudo systemctl restart redis # Linux
Testing Errors
RSpec Test Failures
Error Message:
ActiveRecord::StatementInvalid: PG::UndefinedTable: ERROR: relation "users" does not exist
Cause: Test database not set up properly.
Solution:
# Prepare test database
RAILS_ENV=test bundle exec rails db:create
RAILS_ENV=test bundle exec rails db:migrate
# Or use the combined command
bundle exec rails db:test:prepare
# Reset test database if needed
RAILS_ENV=test bundle exec rails db:drop db:create db:migrate
Error Message:
FactoryBot::DuplicateDefinitionError: Factory already registered
Cause: Factory definitions loaded multiple times.
Solution:
# Clear Spring cache
bundle exec spring stop
# Restart test suite
bundle exec rspec
# Check for duplicate factory definitions
grep -r "FactoryBot.define" spec/
Error Message:
Selenium::WebDriver::Error::WebDriverError: unable to connect to chromedriver
Cause: ChromeDriver not installed or incompatible version.
Solutions:
# Install ChromeDriver
# macOS
brew install chromedriver
# Ubuntu/Debian
sudo apt-get install chromium-chromedriver
# Or use webdrivers gem (should be automatic)
bundle exec rails runner "Webdrivers::Chromedriver.update"
# Run tests in headless mode
HEADLESS=true bundle exec rspec spec/system/
Development Environment Issues
IDE and Editor Problems
Error: Ruby IntelliSense not working, no syntax highlighting.
Solutions:
# Install Ruby LSP
gem install ruby-lsp
# Or add to Gemfile
echo 'gem "ruby-lsp", group: :development' >> Gemfile
bundle install
# Restart VS Code
# Install recommended extensions:
# - Ruby LSP
# - Ruby Solargraph
# - Ruby Test Explorer
Error: Ruby documentation and autocomplete not working.
Solutions:
# Install Solargraph
gem install solargraph
# Generate documentation
bundle exec yard gems
bundle exec solargraph bundle
# Create .solargraph.yml config
solargraph config
# Restart your editor
Git and Version Control Issues
Error: Git commit rejected due to linting errors.
Solutions:
# Fix RuboCop issues
bundle exec rubocop -a
# Fix ESLint issues
pnpm run lint:fix
# Format code
pnpm run format
# Skip hooks temporarily (not recommended)
git commit --no-verify -m "Your commit message"
# Update pre-commit hooks
pre-commit autoupdate
Error: Git LFS or large file warnings.
Solutions:
# Install Git LFS
git lfs install
# Track large files
git lfs track "*.png"
git lfs track "*.jpg"
git lfs track "*.pdf"
# Add .gitattributes
git add .gitattributes
# Check LFS status
git lfs status
Performance Issues
Slow Application Startup
Cause: Large codebase, slow database, or memory issues.
Solutions:
# Use Spring for faster Rails commands
bundle exec spring binstub --all
# Check Spring status
bundle exec spring status
# Restart Spring if needed
bundle exec spring stop
# Increase memory if needed
export RUBY_GC_HEAP_INIT_SLOTS=10000
export RUBY_GC_HEAP_FREE_SLOTS=10000
# Profile startup time
time bundle exec rails runner "puts 'Rails loaded'"
Cause: Database setup, factory creation, or inefficient tests.
Solutions:
# Use parallel testing
bundle exec rspec --parallel
# Profile slow tests
bundle exec rspec --profile
# Use database cleaner strategies
# Add to spec/rails_helper.rb:
# config.use_transactional_fixtures = true
# Optimize factories
# Use build_stubbed instead of create when possible
Email and Communication Issues
Email Delivery Problems
Cause: SMTP configuration or email service issues.
Solutions:
# Install and start MailHog
brew install mailhog # macOS
mailhog
# Configure .env
MAILER_SENDER_EMAIL=dev@chatwoot.local
SMTP_ADDRESS=localhost
SMTP_PORT=1025
# Check web interface
open http://localhost:8025
# Install and start MailHog
brew install mailhog # macOS
mailhog
# Configure .env
MAILER_SENDER_EMAIL=dev@chatwoot.local
SMTP_ADDRESS=localhost
SMTP_PORT=1025
# Check web interface
open http://localhost:8025
# Add to Gemfile
echo 'gem "letter_opener", group: :development' >> Gemfile
bundle install
# Configure in development.rb
# config.action_mailer.delivery_method = :letter_opener
# Emails will open in browser
# Use app password, not regular password
MAILER_SENDER_EMAIL=your-email@gmail.com
SMTP_ADDRESS=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_DOMAIN=gmail.com
SMTP_ENABLE_STARTTLS_AUTO=true
WebSocket Connection Issues
Error: Real-time features not working, WebSocket connection failed.
Solutions:
# Check if ActionCable is mounted
grep -r "mount ActionCable" config/routes.rb
# Check Redis connection
redis-cli ping
# Configure ActionCable for development
# In config/environments/development.rb:
# config.action_cable.url = "ws://localhost:3000/cable"
# config.action_cable.allowed_request_origins = ["http://localhost:3000"]
# Test WebSocket connection
# Open browser console and check for WebSocket errors
Debugging and Logging Issues
Log File Problems
Cause: Excessive logging in development.
Solutions:
# Clear log files
> log/development.log
> log/test.log
# Configure log rotation in development.rb
# config.logger = ActiveSupport::Logger.new("log/development.log", 5, 10.megabytes)
# Reduce log level
# config.log_level = :info
# Use logrotate (Linux)
sudo logrotate -f /etc/logrotate.conf
Debugging Tool Issues
Cause: Debugger not properly configured or running in wrong context.
Solutions:
# Make sure gems are in Gemfile
echo 'gem "pry-rails", group: [:development, :test]' >> Gemfile
echo 'gem "pry-byebug", group: [:development, :test]' >> Gemfile
bundle install
# Use correct debugger syntax
# binding.pry # for Pry
# debugger # for built-in debugger
# byebug # for byebug
# Check if running in correct environment
puts Rails.env
Quick Diagnostic Commands
System Health Check
#!/bin/bash
# health_check.sh - Quick system diagnostic
echo "=== Chatwoot Development Health Check ==="
# Check Ruby version
echo "Ruby version: $(ruby --version)"
# Check Node.js version
echo "Node.js version: $(node --version)"
# Check database connection
if bundle exec rails runner "ActiveRecord::Base.connection.execute('SELECT 1')" > /dev/null 2>&1; then
echo "✅ Database connection: OK"
else
echo "❌ Database connection: FAILED"
fi
# Check Redis connection
if redis-cli ping > /dev/null 2>&1; then
echo "✅ Redis connection: OK"
else
echo "❌ Redis connection: FAILED"
fi
# Check if services are running
echo "Running processes:"
ps aux | grep -E "(rails|sidekiq|webpack|mailhog)" | grep -v grep
# Check ports
echo "Port usage:"
lsof -i :3000,3035,6379,5432,8025 2>/dev/null || echo "No processes found on common ports"
echo "=== Health Check Complete ==="
Environment Validation
#!/bin/bash
# validate_env.sh - Validate development environment
required_vars=(
"RAILS_ENV"
"DATABASE_URL"
"REDIS_URL"
"SECRET_KEY_BASE"
"FRONTEND_URL"
)
echo "=== Environment Variable Check ==="
for var in "${required_vars[@]}"; do
if [ -z "${!var}" ]; then
echo "❌ Missing: $var"
else
echo "✅ Set: $var"
fi
done
echo "=== Dependency Check ==="
commands=("ruby" "node" "psql" "redis-cli" "git")
for cmd in "${commands[@]}"; do
if command -v $cmd > /dev/null 2>&1; then
echo "✅ $cmd: $(command -v $cmd)"
else
echo "❌ $cmd: Not found"
fi
done
Getting Additional Help
If you’re still experiencing issues after trying these solutions:
- Search GitHub Issues: Check if others have reported similar problems
- Check Logs: Look at
log/development.log
for detailed error messages - Discord Community: Join the Chatwoot Discord for real-time help
- Documentation: Review the official documentation
- Create an Issue: If it’s a bug, create a detailed GitHub issue
Creating a Good Bug Report
When reporting issues, include:
## Environment
- OS: [e.g., macOS 13.0, Ubuntu 22.04]
- Ruby version: [e.g., 3.3.3]
- Node.js version: [e.g., 20.10.0]
- Database: [e.g., PostgreSQL 15.0]
## Steps to Reproduce
1. Step one
2. Step two
3. Step three
## Expected Behavior
What you expected to happen
## Actual Behavior
What actually happened
## Error Messages
Full error message and stack trace
## Additional Context
Any other relevant information
This guide covers the most common development issues. For production deployment issues, see the Self-hosted documentation.
- Common Errors and Solutions
- Installation and Setup Errors
- Ruby and Bundler Issues
- Node.js and Package Manager Issues
- Database Errors
- PostgreSQL Connection Issues
- Redis Connection Issues
- Application Runtime Errors
- Rails Server Issues
- Sidekiq Worker Issues
- Testing Errors
- RSpec Test Failures
- Development Environment Issues
- IDE and Editor Problems
- Git and Version Control Issues
- Performance Issues
- Slow Application Startup
- Email and Communication Issues
- Email Delivery Problems
- WebSocket Connection Issues
- Debugging and Logging Issues
- Log File Problems
- Debugging Tool Issues
- Quick Diagnostic Commands
- System Health Check
- Environment Validation
- Getting Additional Help
- Creating a Good Bug Report