Troubleshoot Odoo on Docker Swarm: Tasks, DNS, Websockets

When you troubleshoot Odoo on Docker Swarm, the same handful of failures come up again and again: tasks that restart in a loop, tasks stuck in Pending, Odoo that cannot reach PostgreSQL, healthchecks that kill a working instance, and websockets that fail with a 400 error. This guide gives you the commands to find out which one you have and the fix for each, using an Odoo stack deployed as erp (services erp_odoo and erp_db).

Run the commands on a manager node unless noted otherwise. For how the stack is built, see the Odoo on Docker Swarm pillar guide.

Step 1: Check cluster and service status

Start wide. Two commands tell you whether the problem is a node or a service:

docker node ls
docker service ls

In docker node ls, look at three columns:

• STATUS: Ready or Down. A Down node's tasks are rescheduled elsewhere if there is room.
• AVAILABILITY: Active, Pause (keeps running tasks, takes no new ones) or Drain (no tasks at all). A node someone forgot to reactivate after maintenance is a common cause of Pending tasks.
• MANAGER STATUS: Leader, Reachable or Unreachable. An unreachable manager reduces your margin before quorum is lost.

In docker service ls, the REPLICAS column shows running versus desired tasks. 1/1 is healthy; 0/1 means Odoo is down. To list only the services that are not at their desired count:

docker service ls --format '{{.Name}} {{.Replicas}}' \
  | awk '{split($2, r, "/"); if (r[1] != r[2]) print}'

Useful filters: docker node ls --filter role=manager, docker service ls --filter name=erp_, and docker node ps <node> to see every task on one node.

Step 2: Read the task history

Every restart creates a new task, and Swarm keeps the recent ones. This is where most answers are:

docker service ps erp_odoo --no-trunc

Without --no-trunc, the ERROR column is cut off, and it usually holds the exact reason. To see only the current task, or a compact history:

docker service ps erp_odoo --filter desired-state=running
docker service ps erp_odoo --format '{{.Name}}  {{.Node}}  {{.CurrentState}}  {{.Error}}'

For a single task, docker inspect gives the state, the error and the container's exit code:

docker inspect --format '{{.Status.State}} | {{.Status.Err}} | exit {{.Status.ContainerStatus.ExitCode}}' <task-id>

And read the log of the service, or of one specific failed task:

docker service logs erp_odoo --since 30m --timestamps --tail 300
docker service logs <task-id>

Odoo tasks restarting in a loop (task churn)

If docker service ps shows a new task every minute or two, match the exit code and the last log lines:

Stop the churn first. Each restart buries the useful log further. Roll back the last change, or scale to zero while you investigate:

docker service rollback erp_odoo
docker service scale erp_odoo=0

If the stack sets restart_policy.max_attempts, Swarm eventually stops trying and leaves the service at 0/1 with every task Failed. After fixing the cause, start it again with docker service update --force erp_odoo.

Tasks stuck in Pending

A Pending task means the scheduler cannot find a node for it. docker service ps erp_odoo --no-trunc tells you why:

• no suitable node (insufficient resources on N nodes): the service's reservations do not fit. Swarm schedules on reservations, not real usage. Check what a node offers with docker node inspect <node> --format '{{json .Description.Resources}}', then lower the reservation or add a node.
• scheduling constraints not satisfied: no node matches the placement.constraints. Usually a missing label (docker node update --label-add role=odoo <node>) or a drained node.
• host-mode port already in use: the service publishes a port in host mode and another task already holds it on that node. With update_config.order: start-first this blocks every update forever, because old and new tasks cannot share the port. Use stop-first for host-mode services.
• Max replicas per node reached: max_replicas_per_node is set and there are fewer eligible nodes than replicas.

A related case: tasks that go to Rejected with No such image. Worker nodes pull the image themselves. For a private registry, deploy with docker stack deploy --with-registry-auth -c odoo-stack.yml erp so the credentials reach the workers.

Overlay DNS: Odoo cannot resolve "db"

Swarm's embedded DNS answers service names only for services on a shared overlay network. Test from inside the Odoo container, on the node where it runs (the official Odoo image has getent and the PostgreSQL client tools):

ODOO=$(docker ps -q -f name=erp_odoo | head -n1)
docker exec -it $ODOO getent hosts db          # the service's virtual IP
docker exec -it $ODOO getent hosts tasks.db    # the IP of each running task

• Nothing comes back: Odoo and PostgreSQL are not on the same network, or the database service has no running task. Compare the networks: of both services.
• The database lives in another stack: the short name only works inside one stack. Use the full service name (otherstack_db) and attach Odoo to that stack's network, declared as external.
• db resolves but tasks.db is empty: the service exists but has no running task. Go back to Step 2 for erp_db.
• Names resolve, connections hang: DNS is fine; the overlay data path is not. Check that 4789/udp and 7946/tcp+udp are open between nodes and that the overlay MTU fits the underlay. The Docker Swarm networking guide for Odoo covers both.

Odoo cannot reach PostgreSQL

Test the connection the same way Odoo makes it:

docker exec -it $ODOO pg_isready -h db -p 5432
docker exec -it $ODOO python3 -c "import urllib.request as u; print(u.urlopen('http://localhost:8069/web/health?db_server_status=1').read())"

The second command asks Odoo itself whether it can reach the database server (Odoo 17 and later). Then match the error in the Odoo log:

Too many clients. Every Odoo process keeps its own connection pool, up to db_maxconn (default 64). In prefork mode that is each HTTP worker, each cron worker and the websocket process, times every replica. Set db_maxconn in odoo.conf so that processes x db_maxconn x replicas stays below PostgreSQL's max_connections, with room for backups and admin sessions.

Idle disconnects. If your PostgreSQL server sets idle_session_timeout or idle_in_transaction_session_timeout, Odoo's long-lived background connections get closed while idle. You can switch both off for Odoo's connections only through the standard libpq variable, without touching the server:

    environment:
      PGOPTIONS: "-c idle_session_timeout=0 -c idle_in_transaction_session_timeout=0"

Healthchecks that restart a working Odoo

See the last probe results, with their output, for a running container:

docker inspect --format '{{json .State.Health}}' $ODOO

• Every probe fails with "executable file not found": the healthcheck calls curl or wget, which the official Odoo image does not include. Use Python, which it does include:

      healthcheck:
        test: ["CMD", "python3", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8069/web/health', timeout=8).status == 200 else 1)"]
        interval: 30s
        timeout: 10s
        retries: 5
        start_period: 120s

• Odoo is killed while starting or upgrading modules: start_period is too short for your database. Failures during that window do not count; raise it.
• Every Odoo restarts when PostgreSQL blips: the healthcheck includes a database check (db_server_status=1). Restarting Odoo does not fix PostgreSQL. Keep the healthcheck about Odoo's own HTTP server.
• Restarts under heavy load: probes time out because all workers are busy. Add workers, or allow more retries so a 30-second spike does not trigger a restart, which only makes the load worse.

Websocket 400 errors and "real-time connection lost"

Since Odoo 16, live notifications, Discuss and chat use a websocket at /websocket. When it fails, users see stale screens and the browser console shows a failed WebSocket request with status 400. The Odoo log tells you which case you have:

• Couldn't bind the websocket. Is the connection opened on the evented port (8072)?: Odoo runs with workers above 0, and the proxy sends /websocket to port 8069. In prefork mode, only the gevent process on port 8072 serves websockets. Add a separate route: in Traefik, a router with PathPrefix(`/websocket`) pointing at a service on port 8072.
• Invalid upgrade header, Invalid connection header or Empty or missing header(s): the proxy drops the Upgrade and Connection headers. Traefik passes them through by default. In nginx you need proxy_http_version 1.1 plus proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade" on the websocket location.
• Websocket works, but links and redirects use http:// or the wrong host: proxy_mode is off, so Odoo ignores the X-Forwarded-* headers. Set proxy_mode = True whenever Odoo is behind a proxy.

A related 400: large uploads (database restores, big attachments) failing with "Bad Request: the browser (or proxy) sent a request that this server could not understand". Odoo's HTTP server gives each client socket a 2-second read timeout by default, and a pause in a slow upload ends the request. Raise it with the ODOO_HTTP_SOCKET_TIMEOUT environment variable (in seconds) on the Odoo service.

Updates that never finish or roll back

docker service inspect erp_odoo --format '{{json .UpdateStatus}}'

The state is updating, paused, completed, rollback_started, rollback_paused or rollback_completed, with a message. A rollback after every deploy usually means the new task never passed its healthcheck inside the update_config.monitor window: make monitor longer than start_period plus one healthcheck interval. An update stuck with the new task Pending is usually the host-mode port case above. The zero-downtime deployment guide covers safe update settings.

Node problems

• A node is Down: docker node ps <node> shows what was running there. Check the Docker daemon on the node with systemctl status docker and journalctl -u docker.
• Disk full: image pulls and container starts fail with no space left on device. docker system df shows where the space went. Remove unused images with docker image prune -a, but never prune volumes on a node that holds the database or filestore.

Troubleshooting checklist

1. docker node ls and docker service ls: is it a node or a service?
2. docker service ps --no-trunc: read the ERROR column and the task history.
3. docker service logs: read the last lines before each exit.
4. Stop the churn (rollback or scale to 0) before changing anything else.
5. From inside the Odoo container: getent hosts db, then pg_isready.
6. Check healthcheck results with docker inspect.
7. Change one thing at a time, and write down what you changed.

Most of these problems are easier to catch before users report them. The guide to monitoring Odoo on Swarm sets up alerts for task churn, killed requests and failing scheduled actions.

Easy Instance runs Odoo on Docker Swarm and has already been through these failures, so its instances ship with a Python healthcheck, a separate websocket route, long stop grace periods and connection settings that survive idle timeouts. If you would rather not debug a cluster, see pricing or start a 10-day free trial, no credit card needed.