Skip to main content

Troubleshooting

General​

Check project status​

odoo setup status

View container logs​

docker logs <project_name>_odoo --tail 100 -f

Rebuild everything from scratch​

odoo down
odoo build
odoo -f db reset
odoo up -d

Installation Issues​

Previous zodoo installation​

rm -Rf ~/.odoo/images
bash <(curl -fsSL https://raw.githubusercontent.com/zebroo-tools/zodoo/refs/heads/main/install.sh)

odoo command not found after installation​

# Make sure pipx bin dir is in PATH:
pipx ensurepath
source ~/.bashrc  # or ~/.zshrc

Startup Issues​

Port already in use​

odoo setup next-port    # assigns next free port
odoo reload
odoo up -d

Containers exit immediately​

Check logs:

docker logs <project_name>_odoo

Common causes:

  • Missing or wrong settings → odoo setup status, then fix and odoo reload
  • Database not yet initialized → odoo -f db reset

odoo reload fails​

Make sure you're in the project directory (where .odoo/settings or MANIFEST lives).

after_compose failed: …/images/odoo/__after_compose.py with a traceback means the dependency resolution or the odoo configuration could not be computed. Fix the cause shown in the traceback — odoo build would otherwise produce an image without the project requirements. A typical cause is Module has no path: <name>: a module in install depends on a module that is not in any addons path. Missing dependencies of modules that are only on the uninstall list are ignored with a warning, because those modules are never installed again.

Database Issues​

Broken CSS/JS after update​

odoo setup remove-web-assets
# Log in as admin to regenerate

Database connection refused​

odoo up -d postgres   # start only postgres
odoo db pgactivity    # check if postgres is responding

Reset to clean state​

odoo -f db reset

Restore hangs or fails​

odoo db pgactivity    # check for blocking connections
odoo restart postgres
odoo -f restore odoo-db

Odoo 20: no demo data despite ODOO_DEMO=1, empty time zone list​

From 20.0 on Odoo reads its time zones from the operating system (/usr/share/zoneinfo, package tzdata) instead of pytz. Images built before zodoo shipped tzdata for Odoo 20 have no time zones at all. The base demo data then fails on its first time zone, the update log shows Module base demo data failed to install, installed without demo data, and no other module gets demo data either. In the user form the time zone selection is empty.

If you see either of these, the image is too old. Upgrade zodoo, rebuild and recreate the database - demo data is only loaded when a database is created:

odoo setup upgrade
odoo reload
odoo build odoo
odoo -f db reset

macOS-specific​

rsync errors​

brew install rsync

Docker Desktop issues​

Restart Docker Desktop. Then:

odoo down
odoo up -d

Python version mismatch​

odoo setting ODOO_PYTHON_VERSION=3.12
odoo reload && odoo build

Performance​

Workers and memory​

odoo setting ODOO_WORKERS_WEB=4
odoo setting LIMIT_MEMORY_HARD_WEB=8053063680
odoo reload
odoo restart

Profiling​

pipx runpip zodoo install line_profiler
$ZODOO_PYTHON -m kernprof -l -v odoo reload

AI Assistant (Claude Code / Cursor) issues​

Claude Code runs in a network sandbox. Some URLs are blocked:

  • ✅ github.com, pypi.org, npmjs.org — accessible
  • ❌ docs.zebroo.de — gone entirely. The old Document360 site was retired; internal documentation lives in Odoo Knowledge on odoo.zebroo.de, which is not reachable from the sandbox either

Solution: All documentation is available in this docs/ folder and in CLAUDE.md at the project root. AI tools can read these local files directly.

If Claude Code doesn't know about zodoo commands, point it to:

  • CLAUDE.md in your project root
  • docs/04-command-reference.md