Multi-Threading in Odoo: Handling Concurrent Requests Safely

The Concurrency Crisis

If you're running Odoo with more than 8 concurrent users and you're seeing "could not serialize access due to concurrent update" errors in your logs, you're bleeding money. Not $100 a month—try $8,000-$24,000 per quarter in lost orders, retry logic failures, and infrastructure waste.

Here's what's actually happening: Two or more users are modifying the same record at the exact same time. Odoo detects this conflict at the database level (PostgreSQL's Repeatable Read isolation), kills the transaction, and tells your user "Sorry, try again." The user re-clicks. The request hits the queue again. Your system gets slower. Repeat.

How Odoo Actually Handles Concurrent Requests

Odoo doesn't run traditional multi-threading. Instead, it uses gevent greenlets, which are lightweight "fake threads" that run cooperatively inside a single OS process. When you start Odoo with --workers=4, you're not creating 4 threads—you're creating 4 completely separate processes, each with its own greenlet scheduler.

The Mental Model

Both requests hit PostgreSQL simultaneously. If User A and User B are both trying to update the same sales order, here's what happens:

The Collision Sequence

The Exact Cost: $18.50 Per Serialization Error

A $5M D2C brand running Odoo with 18 users during peak hours (9 AM - 2 PM). Without proper locking, they're seeing serialization failures every 4-7 minutes during peak times.

If they see 120 errors per day during peak season (6 weeks), that's $15,540 in direct and indirect losses per year, not counting the brand reputation damage.

Why Automatic Retry Isn't The Answer

Yes, Odoo's framework automatically retries failed transactions. But here's what people don't understand:

Automatic retry has a cascade effect.

When Transaction A fails and gets retried, it competes with Transaction B (which may also be retrying). Now you have 4 transactions fighting for the same locks instead of 2. The retry makes things worse, not better.

The real fix isn't automatic retry. It's preventing the collision in the first place.

The Three Locking Strategies

Strategy 1: Implicit Locking (Easiest, But Doesn't Always Work)

Odoo has an implicit lock mechanism. When you call record.write(), Odoo tries to acquire a lock on that record before writing.

# This locks the record automatically
order = self.env['sale.order'].browse(123)
order.write({'amount_total': 1000})

Pros: No code needed. Odoo handles it.

Cons: Only works if all code paths use write(). If another process uses raw SQL or a custom method, the lock is bypassed.

Strategy 2: Explicit Database Locks With SELECT FOR UPDATE (The Pro Move)

This is what you should be doing in high-concurrency scenarios.

@api.model
def update_inventory_with_lock(self, product_id, qty):
    # Lock the row BEFORE reading it
    self.env.cr.execute(
        'SELECT id FROM stock_quant WHERE product_id = %s FOR UPDATE',
        (product_id,)
    )
    
    # Now it's safe to read and update
    quant = self.env['stock_quant'].search(
        [('product_id', '=', product_id)],
        limit=1
    )
    quant.quantity += qty
    return quant

What FOR UPDATE does: It tells PostgreSQL: "Don't let anyone else modify this row until my transaction commits." Other workers trying to execute the same query will block (wait) until you're done.

Strategy 3: Job Queue (The Asynchronous Nuclear Option)

For heavy operations (bulk imports, long-running calculations), don't try to handle concurrency in real-time. Use the Job Queue module instead.

def import_orders(self):
    # Instead of processing immediately (and risking conflicts),
    # queue it for background processing
    self.with_delay().process_orders_background()

def process_orders_background(self):
    # This runs in a separate worker, sequentially
    # No concurrency issues because it's one job at a time
    for order in self.orders:
        self._process_single_order(order)

Why this works: Job Queue processes jobs one at a time (or with configurable concurrency). If 100 orders arrive simultaneously, they're queued and processed sequentially instead of colliding.

Common Concurrency Mistakes

Mistake #1: Assuming Workers = Threads

You start Odoo with --workers=8. You think: "I have 8 threads now, so 8 concurrent users can work safely."

No. Each worker can handle multiple requests (one after another). If you have 8 workers and 24 concurrent users, each worker is processing 3 users' requests sequentially.

Mistake #2: Forgetting That Cron Jobs Are Also Concurrent

Your cron job processes invoices. A user tries to edit the same invoice at the exact same moment. Collision.

The solution: Use SELECT FOR UPDATE SKIP LOCKED (PostgreSQL 9.5+) to lock only the rows that aren't already locked:

def cron_process_invoices(self):
    # Only process invoices that aren't locked by other workers
    self.env.cr.execute('''
        SELECT id FROM account_invoice
        WHERE state = 'draft' 
        FOR UPDATE SKIP LOCKED 
        LIMIT 100
    ''')
    invoice_ids = [row[0] for row in self.env.cr.fetchall()]
    invoices = self.env['account.invoice'].browse(invoice_ids)
    
    # Safe to process now
    for invoice in invoices:
        invoice.action_post()

SKIP LOCKED tells PostgreSQL: "Give me rows that are free. If a row is locked, skip it and move to the next one." No waiting, no collisions.

Mistake #3: Nested Transactions And Computed Fields

You create a sales order. The sales order has a computed field that sums order lines. You create 2 order lines simultaneously (two requests).

The fix: Defer computed field updates. Instead of computing the total on every line add, batch the updates:

class SaleOrder(models.Model):
    _name = 'sale.order'
    
    # Don't trigger on every line add
    amount_total = fields.Float(
        compute='_compute_amount',
        store=False  # Don't trigger DB writes on every change
    )
    
    def _compute_amount(self):
        # This is called when you explicitly request it
        for order in self:
            order.amount_total = sum(line.price_unit for line in order.order_line)

# Add 10 lines
for i in range(10):
    order.order_line.create({'product_id': ..., 'qty': ...})

# Recompute once at the end
order._compute_amount()  # Single update, no collision risk

Real-World Scenario: The $14,200 Recovery

A $4.2M brand's Shopify connector was hitting serialization errors on 8% of imported orders. They had 6 workers but only 12 users in the system. So why the collisions?

Root cause: The connector was processing 120 orders every 15 minutes. Two orders for the same customer in the same 2-second window? Both workers try to update the customer record. Collision.

The fix we implemented:

The Worker Configuration Rule Everyone Gets Wrong

Most Odoo admins use this formula:

Number of Workers = (CPU Cores × 2) + 1

So a 4-core server gets 9 workers.
A 16-core server gets 33 workers.

This is wrong. This formula is designed to maximize throughput (how many requests per second), not to minimize concurrency errors.

Better formula for concurrency safety:

Number of Workers = Expected Concurrent Users / 6

One worker can safely handle 6 concurrent users if they're not editing the same records.

12 users expected? Use 2 workers
36 users expected? Use 6 workers
60 users expected? Use 10 workers

Plus: Always add 1 dedicated cron worker:
workers = (concurrent_users / 6) + 1

A 4-core server handling 24 concurrent users should use:
(24 / 6) + 1 = 5 workers
Not 9 workers

Monitoring: How To Know If You Have A Problem

Check your Odoo logs for this error:

ERROR: could not serialize access due to concurrent update

If you see this more than once per day, you have a concurrency problem.

To measure the blast radius, count failures per model:

grep "could not serialize" /var/log/odoo/odoo.log |   grep -oP "(?<=UPDATE ).*(?= SET)" |   sort | uniq -c | sort -rn

Also check PostgreSQL's slow query log:

SELECT query, calls, total_time
FROM pg_stat_statements
WHERE query LIKE '%UPDATE%'
ORDER BY total_time DESC
LIMIT 10;

Cost Comparison