Troubleshooting Guide¶
Common issues and solutions for the Odoo 15 ERP system.
Quick Diagnosis¶
# Check all container status
docker compose ps
# Check container logs
docker compose logs odoo --tail=50
docker compose logs pwa --tail=50
docker compose logs nginx --tail=50
# Run health check
./production_deploy.sh health
# Check disk space
df -h
# Check memory
free -m
Container Issues¶
Container Won't Start¶
Symptoms:
- docker compose up fails
- Container exits immediately
- Status shows "Exited (1)"
Diagnosis:
# Check container logs
docker compose logs odoo
# Check container status
docker compose ps -a
# Inspect container
docker inspect odoo15-jdx-production-odoo-1
Solutions:
| Cause | Solution |
|---|---|
| Port already in use | sudo lsof -i :8069 then stop conflicting process |
| Missing .env file | cp .env.example .env and configure |
| Permission denied | chmod 644 configs/odoo.conf |
| Corrupt image | docker compose build --no-cache |
| Out of disk space | docker system prune -a |
Container Keeps Restarting¶
Symptoms: - Container restarts repeatedly - Status shows "Restarting"
Diagnosis:
# Watch logs in real-time
docker compose logs -f odoo
# Check restart count
docker inspect --format='{{.RestartCount}}' odoo15-jdx-production-odoo-1
Solutions:
# Check for configuration errors
docker compose config
# Recreate container
docker compose up -d --force-recreate odoo
# Full rebuild
docker compose down
docker compose build --no-cache
docker compose up -d
Odoo Issues¶
500 Internal Server Error¶
Symptoms: - Browser shows 500 error - "Internal Server Error" message
Diagnosis:
Common Causes and Solutions:
| Cause | Solution |
|---|---|
| Database not initialized | docker compose exec odoo odoo -i base --stop-after-init -d DATABASE |
| Module syntax error | Fix Python/XML syntax in module |
| Missing dependency | Install required module first |
| Database connection failed | Check PostgreSQL is running |
Module Won't Install¶
Symptoms: - "Module not found" error - Installation fails
Diagnosis:
# Check module exists
ls -la extra-addons/odoo/MODULE_NAME/
# Check manifest
cat extra-addons/odoo/MODULE_NAME/__manifest__.py
# Check Odoo logs
docker compose logs odoo | grep -i "MODULE_NAME"
Solutions:
# 1. Restart Odoo to detect new modules
docker compose restart odoo
# 2. Update module list in Odoo
# Apps > Update Apps List
# 3. Check dependencies are installed
docker compose exec odoo odoo -i dependency_module --stop-after-init -d DATABASE
# 4. Check for Python syntax errors
docker compose exec odoo python -m py_compile /mnt/extra-addons/odoo/MODULE_NAME/models/model.py
Module Won't Update¶
Symptoms: - Changes not appearing after update - "Nothing to update" message
Solutions:
# Force update
docker compose exec odoo odoo -u MODULE_NAME --stop-after-init -d DATABASE
# Restart Odoo
docker compose restart odoo
# Clear browser cache
# Ctrl+Shift+R or Cmd+Shift+R
# Clear Odoo assets cache
docker compose exec odoo odoo shell -d DATABASE
>>> self.env['ir.attachment'].search([('name', 'ilike', 'assets')]).unlink()
>>> self.env.cr.commit()
Slow Performance¶
Symptoms: - Pages load slowly - Timeouts
Diagnosis:
# Check resource usage
docker stats
# Check Odoo workers
docker compose exec odoo ps aux | grep odoo
# Check PostgreSQL slow queries
docker compose exec db psql -U odoo -d DATABASE -c "SELECT * FROM pg_stat_activity WHERE state = 'active';"
Solutions:
| Issue | Solution |
|---|---|
| Not enough workers | Increase workers in odoo.conf |
| Database needs vacuum | docker compose exec db vacuumdb -U odoo -d DATABASE |
| Missing indexes | Add database indexes |
| Large attachments | Move to S3 storage |
Database Issues¶
Cannot Connect to Database¶
Symptoms: - "Connection refused" error - "Database does not exist"
Diagnosis:
# Check PostgreSQL is running
docker compose ps db
# Test connection
docker compose exec db pg_isready -U odoo
# Check database exists
docker compose exec db psql -U odoo -l
Solutions:
# Restart database
docker compose restart db
# Check PostgreSQL logs
docker compose logs db
# Create database if missing
docker compose exec db createdb -U odoo DATABASE_NAME
Database Locked¶
Symptoms: - "Database is locked" error - Operations timeout
Solutions:
# Check active connections
docker compose exec db psql -U odoo -d DATABASE -c "SELECT * FROM pg_stat_activity;"
# Terminate idle connections
docker compose exec db psql -U odoo -d DATABASE -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'DATABASE' AND state = 'idle';"
Database Corruption¶
Symptoms: - Strange errors - Missing data
Solutions:
# Check database integrity
docker compose exec db pg_dump -U odoo DATABASE > /dev/null
# Restore from backup
./scripts/restore.sh backup_file.sql.gz
# Reindex database
docker compose exec db reindexdb -U odoo -d DATABASE
PWA Issues¶
PWA Not Loading¶
Symptoms: - Blank page - 502 Bad Gateway
Diagnosis:
# Check PWA container
docker compose ps pwa
# Check PWA logs
docker compose logs pwa
# Test PWA directly
curl http://localhost:5000/health
Solutions:
# Restart PWA
docker compose restart pwa
# Rebuild PWA
docker compose build --no-cache pwa
docker compose up -d pwa
# Check Nginx proxy config
cat nginx/conf.d/default.conf | grep -A 10 "location /pwa"
PWA Shows 503 Error¶
Symptoms: - "Service Unavailable" on health check - App works but health fails
Explanation: This is expected "degraded" mode when Odoo credentials are not configured.
Solution:
Configure ODOO_URL, ODOO_DB, ODOO_USERNAME, ODOO_PASSWORD in .env
PWA Offline Not Working¶
Symptoms: - App doesn't work offline - Service worker not registered
Diagnosis:
# Check service worker file exists
ls -la pwa/static/sw.js
# Check browser console for errors
# Open DevTools > Console
Solutions: - Clear browser cache and re-register service worker - Check HTTPS is enabled (required for service workers) - Verify manifest.json is valid
Nginx Issues¶
502 Bad Gateway¶
Symptoms: - Nginx returns 502 - Backend not reachable
Diagnosis:
# Check Nginx logs
docker compose logs nginx
# Check upstream services
curl http://localhost:8069 # Odoo
curl http://localhost:5000 # PWA
Solutions:
# Restart Nginx
docker compose restart nginx
# Check Nginx config
docker compose exec nginx nginx -t
# Verify upstream hosts
docker compose exec nginx cat /etc/hosts
SSL Certificate Issues¶
Symptoms: - "Certificate expired" - "Certificate not trusted"
Solutions:
# Check certificate expiry
openssl x509 -in nginx/ssl/live/domain/cert.pem -noout -dates
# Renew Let's Encrypt certificate
./production_deploy.sh init-ssl
# Restart Nginx
docker compose restart nginx
Network Issues¶
Services Can't Communicate¶
Symptoms: - "Connection refused" between containers - DNS resolution fails
Diagnosis:
# Check network
docker network ls
docker network inspect odoo15-jdx-production_default
# Test connectivity from container
docker compose exec odoo ping db
docker compose exec nginx ping odoo
Solutions:
Port Already in Use¶
Symptoms: - "Bind: address already in use"
Diagnosis:
Solutions:
# Kill process
sudo kill -9 PID
# Or change port in docker-compose.yml
ports:
- "8070:8069" # Use different host port
Git Issues¶
Merge Conflicts¶
Symptoms:
- git pull fails with conflicts
- "Automatic merge failed"
Solutions:
# View conflicts
git status
# Edit conflicted files
# Look for <<<<<<< HEAD markers
# After resolving
git add .
git commit -m "Resolve merge conflicts"
Accidental Commit to Main¶
Solutions:
# If not pushed yet
git reset HEAD~1
git checkout develop
git cherry-pick COMMIT_HASH
# If already pushed (careful!)
git revert COMMIT_HASH
git push origin main
Backup/Restore Issues¶
Backup Fails¶
Symptoms: - Backup script errors - Incomplete backup file
Diagnosis:
# Check disk space
df -h
# Check backup script permissions
ls -la scripts/backup.sh
# Run manually with debug
bash -x scripts/backup.sh full
Solutions:
# Free disk space
docker system prune -a
# Fix permissions
chmod +x scripts/backup.sh
# Manual backup
docker compose exec db pg_dump -U odoo DATABASE | gzip > backup.sql.gz
Restore Fails¶
Symptoms: - Restore script errors - Data not appearing after restore
Solutions:
# Drop and recreate database
docker compose exec db dropdb -U odoo DATABASE
docker compose exec db createdb -U odoo DATABASE
# Restore
gunzip -c backup.sql.gz | docker compose exec -T db psql -U odoo -d DATABASE
# Restart Odoo
docker compose restart odoo
Performance Troubleshooting¶
High CPU Usage¶
Diagnosis:
# Find CPU-heavy containers
docker stats
# Find heavy processes inside container
docker compose exec odoo top
Solutions: - Increase Odoo workers - Add database indexes - Optimize slow queries - Scale horizontally
High Memory Usage¶
Diagnosis:
# Check memory per container
docker stats --format "table {{.Name}}\t{{.MemUsage}}"
# Check system memory
free -m
Solutions: - Set memory limits in docker-compose.yml - Reduce Odoo workers - Increase swap space - Upgrade server RAM
High Disk Usage¶
Diagnosis:
# Check disk usage
df -h
# Find large files
du -sh /var/lib/docker/*
# Check Docker usage
docker system df
Solutions:
# Clean Docker
docker system prune -a --volumes
# Clean old backups
find /backups -mtime +30 -delete
# Clean Odoo sessions
docker compose exec odoo odoo shell -d DATABASE
>>> self.env['ir.sessions'].search([]).unlink()
Module Upgrade Issues¶
View Conflict in purchase_stock¶
Symptoms:
- Element '<xpath expr="//div[@t-elif='o.date_order']">' cannot be located in parent view
- Error occurs when upgrading stock module after production restore
Cause:
The purchase_stock module tries to extend a view element that doesn't exist in the parent purchase report template. This happens when the production database has customized views.
Fix:
Delete the conflicting views and upgrade purchase before stock:
# Delete conflicting views
docker compose exec db psql -U odoo -d odoo_test -c "
DELETE FROM ir_ui_view WHERE inherit_id IN (
SELECT id FROM ir_ui_view WHERE name = 'report_purchaseorder_document' AND inherit_id IS NULL
);
DELETE FROM ir_ui_view WHERE name = 'report_purchaseorder_document' AND inherit_id IS NULL;
"
# Upgrade purchase first, then stock
docker compose run --rm odoo odoo -d odoo_test -u purchase --stop-after-init
docker compose run --rm odoo odoo -d odoo_test -u stock --stop-after-init
REST API Issues¶
Binary Attachment Error (UTF-8 Decode)¶
Symptoms:
- 'utf-8' codec can't decode byte 0x89 in position 0: invalid start byte
- 403 error when creating ir.attachment with binary files (PNG, PDF, etc.)
- Works on clean database but fails after production restore
Cause:
The web_editor module (installed in production) adds a raw computed field to ir.attachment that returns binary bytes. The REST API tried to UTF-8 decode this field in the response, which fails for non-text binary data like images.
Why it works on clean DB:
On a clean install with just helpdesk module, web_editor may not be installed as a dependency. In production, web_editor is typically installed by website or other modules.
Fix:
Edit extra-addons/odoo/restapi/controllers/main.py around line 912:
# Change this:
if isinstance(val[v], bytes):
val[v] = val[v].decode('utf-8')
# To this:
if isinstance(val[v], bytes):
# Base64 encode binary data (e.g., ir.attachment.raw)
# UTF-8 decode fails on non-text binary data like images
val[v] = base64.b64encode(val[v]).decode('utf-8')
After the fix, restart Odoo:
Quick Reference¶
Emergency Commands¶
# Stop everything
docker compose down
# Start everything
docker compose up -d
# Full restart
docker compose down && docker compose up -d
# Nuclear option (rebuild all)
docker compose down -v
docker compose build --no-cache
docker compose up -d
Log Locations¶
| Service | Command |
|---|---|
| Odoo | docker compose logs odoo |
| PostgreSQL | docker compose logs db |
| PWA | docker compose logs pwa |
| Nginx | docker compose logs nginx |
| All | docker compose logs |