Odoo Module Upgrade Failure Runbook (CLI-First)

When a module upgrade fails mid-release, the worst outcome is improvising from memory. This runbook gives operators a deterministic CLI path: stabilize, diagnose, and either fix-forward or rollback.

Failure signals worth treating as an incident

• odoo-bin -u <module> exits non-zero.
• Repeated worker crashes after deploy (Traceback, migration errors, missing columns).
• HTTP 500 spike immediately after module update.
• Queue/cron jobs start failing against the upgraded model.

Before you touch production

1. Freeze write traffic (maintenance page, read-only mode, or load balancer drain).
2. Confirm the release SHA and module list you just deployed.
3. Identify your latest verified PostgreSQL backup and timestamp.
4. Snapshot current DB state before deeper recovery work.

# Example checkpoint before remediation
pg_dump -Fc "$ODOO_DB" > "/var/backups/odoo/pre-recovery-$(date +%F-%H%M).dump"

Step 1 — Capture the exact failure context

# Service-level errors from this boot window
journalctl -u odoo --since "30 min ago" --no-pager | tail -n 200

# App-level traceback patterns
grep -E "Traceback|psycopg2|ProgrammingError|KeyError" /var/log/odoo/odoo-server.log | tail -n 120

Focus on the first real migration failure, not downstream noise. Typical root causes: missing dependency module, invalid XML data update, schema mismatch from partial migration.

Step 2 — Decide: fix-forward or rollback

Fix-forward (preferred when cause is clear and low risk)

Use this path if you can patch quickly and validate in staging first:

1. Patch module code/data.
2. Re-run upgrade on staging with production-like data.
3. Re-run upgrade in production with traffic still frozen.
4. Smoke test core objects (sale orders, invoices, inventory moves).

# Example: controlled module upgrade
odoo-bin -c /etc/odoo/odoo.conf -d "$ODOO_DB" -u my_custom_module --stop-after-init
systemctl restart odoo

Rollback (preferred when diagnosis is unclear or blast radius is widening)

Use rollback when uptime and data integrity are at risk.

# 1) Stop app workers cleanly
sudo systemctl stop odoo

# 2) Restore last known-good backup
dropdb "$ODOO_DB"
createdb "$ODOO_DB"
pg_restore -d "$ODOO_DB" "/var/backups/odoo/last-known-good.dump"

# 3) Bring application back
sudo systemctl start odoo

Then redeploy the previous known-good release SHA before reopening traffic.

Step 3 — Reopen safely

• Validate login + one end-to-end transaction per critical flow.
• Confirm queue workers and cron are healthy.
• Watch error rate and DB locks for at least 15–30 minutes.

Post-incident hardening checklist

• Add preflight check for missing module dependencies.
• Require a restore drill result younger than 7 days before module upgrades.
• Keep upgrade command history in version control (Makefile, justfile, or runbook scripts).
• Add an explicit rollback section to every release PR.

A good runbook is not about cleverness. It is about making the safe path the default path.