Skip to main content
This guide provides solutions to common issues you may encounter when working with Bench.

​
Common Issues and Solutions

​
Bench Init Failures

​
Issue: Permission denied during init

Error: 
Permission denied: '/home/user/frappe-bench'
Solution:
  1. Check directory permissions: 
    ls -la ~/
  2. Ensure you own the parent directory: 
    sudo chown -R $USER:$USER ~/
  3. Don’t use sudo with bench init: 
    bench init frappe-bench  # Correct
sudo bench init frappe-bench  # Wrong

​
Issue: Python version error

Error: 
Python 3.8 or higher required
Solution:
  1. Check Python version: 
    python3 --version
  2. Specify Python path: 
    bench init frappe-bench --python python3.10
  3. Install newer Python: 
    # Ubuntu/Debian
sudo apt update
sudo apt install python3.10 python3.10-venv

​
Issue: Node.js version incompatible

Error: 
Node version must be >= 18
Solution:
  1. Install Node.js 18+: 
    curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
  2. Verify installation: 
    node --version
npm --version

​
Database Issues

​
Issue: Cannot connect to database

Error: 
Access denied for user 'root'@'localhost'
Solution:
  1. Check MariaDB is running: 
    sudo systemctl status mariadb
sudo systemctl start mariadb
  2. Verify root password: 
    mysql -u root -p
  3. Reset MariaDB root password: 
    sudo mysql

    ALTER USER 'root'@'localhost' IDENTIFIED BY 'newpassword';
FLUSH PRIVILEGES;
EXIT;
  4. Update bench config: 
    # Edit sites/common_site_config.json
{
  "db_host": "localhost",
  "db_port": 3306
}

​
Issue: Database already exists

Error: 
Database already exists
Solution:
  1. Drop existing database: 
    bench drop-site sitename.com
  2. Or use —force flag: 
    bench new-site sitename.com --force
  3. Or manually drop in MySQL: 
    mysql -u root -p

    DROP DATABASE `_1234567890abcdef`;

​
Issue: Database connection timeout

Error: 
OperationalError: (2003, "Can't connect to MySQL server")
Solution:
  1. Check MySQL is listening: 
    sudo netstat -tlnp | grep 3306
  2. Verify bind address in MariaDB config: 
    sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf
    Change: 
    bind-address = 127.0.0.1
  3. Restart MariaDB: 
    sudo systemctl restart mariadb

​
Port Conflicts

​
Issue: Port already in use

Error: 
[ERROR] Port 8000 already in use
Solution:
  1. Find process using port: 
    lsof -ti:8000
sudo netstat -tlnp | grep :8000
  2. Kill the process: 
    kill -9 $(lsof -ti:8000)
  3. Or change bench port in sites/common_site_config.json: 
    {
  "webserver_port": 8080,
  "socketio_port": 9001
}
  4. Restart bench: 
    bench start

​
Issue: Redis port conflict

Error: 
Redis connection failed on port 11000
Solution:
  1. Check Redis processes: 
    ps aux | grep redis
  2. Regenerate Redis config: 
    bench setup redis
  3. Restart Redis: 
    bench restart

​
Permission Errors

​
Issue: Permission denied on files

Error: 
PermissionError: [Errno 13] Permission denied: 'sites/assets'
Solution:
  1. Fix ownership: 
    sudo chown -R $USER:$USER ~/frappe-bench
  2. Fix permissions: 
    find ~/frappe-bench -type d -exec chmod 755 {} \;
find ~/frappe-bench -type f -exec chmod 644 {} \;
chmod +x ~/frappe-bench/env/bin/*

​
Issue: Cannot write to logs

Error: 
Permission denied: 'logs/bench.log'
Solution:
  1. Create logs directory: 
    mkdir -p ~/frappe-bench/logs
  2. Set permissions: 
    chmod 755 ~/frappe-bench/logs

​
Issue: Sites directory permission error

Error: 
OSError: [Errno 13] Permission denied: 'sites/sitename'
Solution:
  1. Fix sites directory: 
    sudo chown -R $USER:$USER ~/frappe-bench/sites
chmod 755 ~/frappe-bench/sites
  2. For production setup: 
    sudo bench setup production frappe --user $USER

​
Asset Build Failures

​
Issue: Build fails with memory error

Error: 
JavaScript heap out of memory
Solution:
  1. Increase Node.js memory: 
    export NODE_OPTIONS="--max-old-space-size=4096"
bench build
  2. Or build apps individually: 
    bench build --app frappe
bench build --app erpnext

​
Issue: Module not found during build

Error: 
Error: Cannot find module 'rollup'
Solution:
  1. Install Node dependencies: 
    bench setup requirements --node
  2. Clear node_modules and reinstall: 
    rm -rf apps/frappe/node_modules
cd apps/frappe
yarn install
cd ../..
bench build

​
Issue: Sass compilation error

Error: 
Sass compilation failed
Solution:
  1. Clear cache: 
    bench --site all clear-cache
  2. Force rebuild: 
    bench build --force
  3. Reinstall Python dependencies: 
    bench setup requirements --python

​
Production Issues

​
Issue: Supervisor not starting

Error: 
supervisorctl: command not found
Solution:
  1. Install supervisor: 
    sudo apt-get install supervisor
  2. Check supervisor status: 
    sudo systemctl status supervisor
sudo systemctl start supervisor
  3. Regenerate config: 
    bench setup supervisor
sudo supervisorctl reread
sudo supervisorctl update

​
Issue: NGINX configuration error

Error: 
nginx: configuration file test failed
Solution:
  1. Test NGINX config: 
    sudo nginx -t
  2. Check for syntax errors: 
    cat config/nginx.conf
  3. Regenerate NGINX config: 
    bench setup nginx
  4. Check error details: 
    sudo tail -f /var/log/nginx/error.log

​
Issue: Workers not processing jobs

Error: Background jobs stuck in queue Solution:
  1. Check worker status: 
    sudo supervisorctl status
  2. Restart workers: 
    sudo supervisorctl restart all
  3. Check worker logs: 
    tail -f logs/worker.error.log
  4. Clear job queue: 
    bench --site sitename clear-cache
bench --site sitename clear-queue

​
SSL Certificate Issues

​
Issue: Certbot command not found

Error: 
Certbot is not installed
Solution:
  1. Install certbot: 
    # Ubuntu/Debian
sudo apt-get install certbot python3-certbot-nginx
  2. Verify installation: 
    certbot --version

​
Issue: Certificate verification failed

Error: 
Failed authorization procedure
Solution:
  1. Verify DNS is pointing to server: 
    dig sitename.com +short
  2. Ensure port 80 is open: 
    sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
  3. Check NGINX is running: 
    sudo systemctl status nginx
  4. Try standalone mode: 
    sudo systemctl stop nginx
sudo certbot certonly --standalone -d sitename.com
sudo systemctl start nginx

​
Issue: DNS multitenancy not enabled

Error: 
You cannot setup SSL without DNS Multitenancy
Solution:
  1. Enable multitenancy: 
    bench config dns_multitenant on
  2. Regenerate config: 
    bench setup nginx
sudo bench setup reload-nginx

​
Update Issues

​
Issue: Update fails with merge conflicts

Error: 
error: Your local changes would be overwritten by merge
Solution:
  1. Stash local changes: 
    cd apps/frappe
git stash
cd ../..
bench update --pull
  2. Or reset to remote: 
    cd apps/frappe
git reset --hard origin/version-15
cd ../..
bench update
Resetting will lose local changes. Ensure you have backups.

​
Issue: Migration fails

Error: 
Migration failed for site
Solution:
  1. Check error logs: 
    tail -f logs/bench.log
  2. Backup first: 
    bench --site sitename backup
  3. Try manual migration: 
    bench --site sitename migrate
  4. If fails, restore backup: 
    bench --site sitename restore /path/to/backup.sql.gz

​
Issue: Dependencies not updating

Error: 
ImportError: No module named 'module_name'
Solution:
  1. Update requirements: 
    bench setup requirements
  2. Update specific app requirements: 
    bench setup requirements --app erpnext
  3. Reinstall pip packages: 
    ./env/bin/pip install -r apps/frappe/requirements.txt --upgrade

​
Log Locations

Knowing where to look for logs is crucial for debugging:

​
Bench logs

# Main bench log
logs/bench.log

# Web server errors
logs/web.error.log

# Worker errors
logs/worker.error.log

# Worker output
logs/worker.log

​
System logs

# Supervisor
sudo tail -f /var/log/supervisor/supervisord.log

# NGINX access
sudo tail -f /var/log/nginx/access.log

# NGINX errors
sudo tail -f /var/log/nginx/error.log

# MariaDB errors
sudo tail -f /var/log/mysql/error.log

# System log
sudo tail -f /var/log/syslog

​
Application logs

# Site error logs
tail -f sites/sitename/logs/error.log

# Site request logs  
tail -f sites/sitename/logs/web.access.log

​
Debugging Tools

​
Check bench health

bench version
bench config dns_multitenant
bench --site all list-apps

​
Monitor processes

# Check running processes
ps aux | grep frappe
ps aux | grep redis
ps aux | grep nginx

# Monitor resource usage
top
htop

​
Database inspection

# Connect to site database
bench --site sitename mariadb

# Show tables
SHOW TABLES;

# Check specific table
SELECT * FROM tabUser LIMIT 10;

​
Redis inspection

# Connect to Redis
redis-cli -p 13000

# Check keys
KEYS *

# Monitor commands
MONITOR

​
Cache Issues

​
Issue: Stale cache causing problems

Solution:
  1. Clear site cache: 
    bench --site sitename clear-cache
  2. Clear all sites: 
    bench --site all clear-cache
  3. Clear Redis: 
    redis-cli -p 13000 FLUSHDB
  4. Clear website cache: 
    bench --site sitename clear-website-cache

​
Getting Help

If you’re still stuck:
  1. Check documentation: Review official Frappe/ERPNext docs
  2. Search forums: https://discuss.frappe.io/
  3. GitHub issues: Check existing issues on GitHub
  4. Community chat: Join Frappe Telegram/Discord
  5. Verbose logs: Run commands with -v flag for detailed output: 
    bench -v update

​
Common Command Quick Reference

# Restart everything
bench restart

# Clear cache and rebuild
bench --site all clear-cache
bench build --force

# Fix permissions
sudo chown -R $USER:$USER ~/frappe-bench

# Check services
sudo supervisorctl status
sudo systemctl status nginx
sudo systemctl status mariadb

# View logs
tail -f logs/bench.log
sudo tail -f /var/log/nginx/error.log

# Database access
bench --site sitename mariadb

# Python console
bench --site sitename console

# Migrate
bench --site sitename migrate

# Backup
bench --site sitename backup --with-files

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us