Fix Odoo XML-RPC Connection Refused Error: Complete Troubleshooting Guide

The XML-RPC Connection Refused Error

XML-RPC is the primary external API protocol for Odoo. When you try to connect from an external script, integration tool, or another application and get ConnectionRefusedError: [Errno 111] Connection refused, your client cannot reach the Odoo XML-RPC endpoint at all. This is a network-level problem, not an authentication issue.

What the Error Looks Like

import xmlrpc.client
url = 'http://your-server:8069'
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
common.version()

# Traceback:
# ConnectionRefusedError: [Errno 111] Connection refused
# --- or ---
# OSError: [Errno 61] Connection refused
# --- or ---
# socket.error: [Errno 10061] No connection could be made

The error number varies by OS — 111 on Linux, 61 on macOS, 10061 on Windows — but the cause is the same: nothing is listening on that port at that address.

Common Causes and Fixes

Cause 1: Odoo Is Not Running

The most basic cause. Odoo is stopped or crashed.

# Check if Odoo is running
sudo systemctl status odoo
# Or check the port directly
ss -tlnp | grep 8069

# If not running, start it
sudo systemctl start odoo

# Check logs for crash reason
tail -100 /var/log/odoo/odoo-server.log

Cause 2: Odoo Bound to localhost Only

By default, Odoo may bind to 127.0.0.1, rejecting connections from external IPs.

# In odoo.conf:
# BAD — only accepts local connections
xmlrpc_interface = 127.0.0.1

# FIX — accept connections from all interfaces
xmlrpc_interface = 0.0.0.0

# Or leave it empty (same as 0.0.0.0)
xmlrpc_interface =

After changing, restart Odoo and verify: ss -tlnp | grep 8069 should show 0.0.0.0:8069 instead of 127.0.0.1:8069.

Cause 3: Wrong Port

Odoo defaults to port 8069, but your installation may use a different port.

# Check the actual port in odoo.conf
grep -E '^(http_port|xmlrpc_port)' /etc/odoo/odoo.conf

# http_port = 8069   (Odoo 14+)
# xmlrpc_port = 8069  (Odoo 13 and earlier)

# If using Docker, check port mapping
docker ps | grep odoo
# PORTS: 0.0.0.0:8069->8069/tcp

Cause 4: Firewall Blocking the Port

The server firewall may block port 8069 from external access.

# Check UFW (Ubuntu)
sudo ufw status | grep 8069

# If not listed, allow it
sudo ufw allow 8069/tcp

# Check iptables
sudo iptables -L -n | grep 8069

# Cloud firewalls (AWS, GCP, Azure)
# Check security groups / firewall rules in your cloud console
# Ensure inbound TCP 8069 is allowed from your client IP

Cause 5: Connecting Through Nginx Without XML-RPC Proxy

If Odoo is behind nginx on port 443, you need to connect to the proxied URL, not port 8069 directly.

# WRONG — port 8069 may be firewalled
url = 'http://your-domain.com:8069'

# RIGHT — go through nginx proxy
url = 'https://your-domain.com'
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')

# Make sure nginx proxies /xmlrpc paths
# In nginx config:
location /xmlrpc {
    proxy_pass http://127.0.0.1:8069;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Cause 6: SSL Certificate Issues

When connecting over HTTPS, self-signed or expired certificates cause connection failures.

import xmlrpc.client
import ssl

# Create unverified context (development only)
context = ssl._create_unverified_context()
url = 'https://your-domain.com'
common = xmlrpc.client.ServerProxy(
    f'{url}/xmlrpc/2/common',
    context=context
)
print(common.version())

For production, fix the SSL certificate instead of disabling verification.

Cause 7: Docker Network Isolation

If Odoo runs in Docker, the container port may not be exposed to the host.

# Check if port is mapped
docker ps --format '{{.Names}}: {{.Ports}}' | grep odoo

# If port is not mapped, update docker-compose.yml:
services:
  odoo:
    ports:
      - "8069:8069"

# For internal Docker network access, use the service name
# From another container in the same network:
url = 'http://odoo:8069'

Testing the Connection

Use these commands to diagnose the issue layer by layer:

# 1. Can you reach the port at all?
telnet your-server 8069

# 2. Does Odoo respond to HTTP?
curl -s http://your-server:8069/web/login | head -5

# 3. Does XML-RPC respond?
curl -s http://your-server:8069/xmlrpc/2/common

# 4. Full Python test
python3 -c "
import xmlrpc.client
common = xmlrpc.client.ServerProxy('http://your-server:8069/xmlrpc/2/common')
print(common.version())
"

Complete Working Example

import xmlrpc.client

url = 'https://your-domain.com'
db = 'your_database'
username = 'admin'
password = 'your_api_key_or_password'

# Authenticate
common = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/common')
uid = common.authenticate(db, username, password, {})
print(f'Authenticated as UID: {uid}')

# Call methods
models = xmlrpc.client.ServerProxy(f'{url}/xmlrpc/2/object')
partners = models.execute_kw(
    db, uid, password, 'res.partner', 'search_read',
    [[['is_company', '=', True]]],
    {'fields': ['name', 'email'], 'limit': 5}
)
for p in partners:
    print(p['name'], p['email'])

When to Use JSON-RPC Instead

Odoo also supports JSON-RPC at /jsonrpc. If XML-RPC gives persistent issues, JSON-RPC is an alternative that works through standard HTTP POST requests and is often easier to route through proxies and load balancers.