# Troubleshooting Odoo

When Odoo is not working correctly, the cause is almost always in one of three places. These are the Odoo service itself, the Nginx reverse proxy in front of it, or the PostgreSQL database behind it. This page shows where the logs live and how to work through the most common issues.

## Where to find the logs

Paths below use `<user>` for the system user and `[app/]` for the optional `app_name` subfolder (omit it for a single Odoo on the account).

| Component | Where |
| --- | --- |
| Odoo application log | `/var/www/<user>/[app/]logs/odoo.log` |
| Odoo service (systemd) | `journalctl --user -u [app-]application.service` |
| Odoo config in use | `/var/www/<user>/[app/]conf/odoo.conf` |
| Nginx access/error | `/var/log/nginx/` (host-level access and error logs) |
| PostgreSQL | system PostgreSQL log (e.g. `/var/log/postgresql/`) |

> [!NOTE]
> The Odoo service is a **systemd user service**, so use `systemctl --user` and `journalctl --user`. Its stdout is appended to `logs/odoo.log`, which is the first file to check.

Also use the host [Health](../../platform/hosts/health.md) tab for live CPU/memory/service status, and review recent deploys in [History](../../platform/hosts/revisions.md) to see whether a change coincided with the problem.

## Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Service won't start | No real `odoo.conf` (only the `.sample`), bad `addons_path`, or Python/env error | Copy `odoo.conf.sample` to `odoo.conf`, verify `addons_path` points to existing folders, then check `journalctl --user` and `logs/odoo.log` for the traceback. |
| "database connection failed" / role errors | PostgreSQL down, wrong `db_user`/`db_password`, or `db_host`/`db_port` mismatch | Confirm PostgreSQL is running on the [Services](../../platform/hosts/services.md) tab; verify the role, database name (`<user>_db`) and port `5432` in `odoo.conf`. |
| 502 Bad Gateway from Nginx | Odoo process not listening on the main port (`8069`) | Check the service is running and started cleanly; confirm `xmlrpc_port`/`main_port` matches the Nginx upstream. |
| Live chat / notifications don't update | Websocket traffic not reaching the gevent port (`8072`) | Ensure the `odoo.websocket_port` and Nginx `/websocket` (or `/longpolling` on Odoo 15 and earlier) routing are consistent; restart the service. |
| Workers crash or restart under load | `limit_memory_soft`/`limit_memory_hard` exceeded, or too many workers for available RAM | Reduce `workers` or raise the memory limits with evidence; watch [Health](../../platform/hosts/health.md). See [Best practices](best-practices.md). |
| Module changes don't take effect | Module not installed/upgraded | Restart with `-u <module>` (or `-u all`) once, on a staging clone first, then remove the flag. |
| Attachments / images 404 | Filestore path or `x_sendfile` mismatch | Confirm `data_dir`/filestore folder exists and the Nginx `/web/filestore` location points to it. |

## A troubleshooting workflow

1. **Check [Health](../../platform/hosts/health.md)** for CPU, memory, and whether the Odoo and PostgreSQL services are up.
2. **Read the relevant log** - start with `logs/odoo.log` and `journalctl --user -u [app-]application.service`, then Nginx and PostgreSQL logs as needed.
3. **Check the last deploy in [History](../../platform/hosts/revisions.md).** If a recent change broke things, revert and re-apply via [Publish](../../platform/hosts/publishing.md).
4. **Verify services are running** from the host [Services](../../platform/hosts/services.md) tab. Restart the Odoo service and PostgreSQL if needed.

## Getting help

If you are still stuck, reach out via [Support](../../platform/support.md) with the relevant log excerpts, and review the general [Troubleshooting](../../platform/troubleshooting.md) guide for platform-wide checks.

## Related

- [Deploy Odoo on TurboStack](deploy.md)
- [Odoo best practices](best-practices.md)
- [Health](../../platform/hosts/health.md)
- [Support](../../platform/support.md)