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

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

#!/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.

Environment Variables for Development Telegram App Integration Setup

Built with

Show your support! Star us on GitHub ⭐️

Star