Verification and troubleshooting

How to check that Odoo came up, and what the most common errors mean.

What is installed here

sudo invok list

The instances this machine carries, their state, database and directory, and the manifest each one lives in. It needs root: the manifests are 0600 root, and a listing that silently came up empty for lack of privileges would be worse than a refusal.

Verification

# Service state (N = short version, e.g. 18)
systemctl status odoo18
journalctl -u odoo18 -n 50 --no-pager

# Local helper command (after reloading the shell)
source ~/.bashrc
odoo status        # or: start | stop | restart | dev

# Is it reachable?
curl -I http://127.0.0.1:8069

Open http://<host>:8069 (or through Nginx on 80/443 if configured) and log in with the master password.

The installer log

The whole run — errors and rollback included — is in:

sudo cat /var/log/invok.log

It is the artifact to keep and to send for a post-mortem. It never contains the password, and it survives the rollback: it matters most when something went wrong.

Common errors

Symptom	Cause	What to do
“port 8069 already in use”	another process holds the port	free it, or use a different --port
“unsupported operating system”	OS outside Ubuntu ≥ 22.04 / Debian ≥ 11 / Fedora ≥ 40	use a supported OS
“the gevent build failed, and this system runs Python 3.x”	the interpreter is newer than Odoo's pins and the distribution packages none that they cover	it is not the build environment: you need a Python covered by the pins, or an Odoo version that pins yours — see Multi-distribution support
“this system's PostgreSQL cluster is configured at …”	a drop-in moves PGDATA elsewhere; the installer only knows how to handle the default path	remove the drop-in, or install on a machine with the standard PGDATA
“must be run as root … through sudo”	started without sudo, or as root directly	run sudo invok from a normal user
“database '…' already existed … initialisation refused”	a database with that name is already there (the anti-write protection)	use a different --db-name, or an empty database created by the installer — see The rollback model
“wkhtmltopdf checksum unavailable … installation refused”	the checksum pins are not populated	populate the pins — see Security
“admin_passwd='admin' requires a confirmation … non-interactive”	weak password in non-interactive mode	set a password other than admin
“another installation is in progress (lock …)”	a run is already active	wait for it to finish, or remove /run/invok.lock if you are certain none is
“a completed installation is already registered on this machine”	there is a manifest from a finished installation	sudo invok rollback to remove it, or --force to install over it (the previous manifest is archived, not deleted)
“the requested parameters name different artifacts”	you are resuming an interrupted installation with a different --db-name/user/version	re-run with the same parameters, or rollback to clean up first
“system user '…' already exists, but its home … belongs to root”	the user was already there and /opt/odoo is root's, not created by us	sudo chown -R odoo:odoo /opt/odoo if that directory is meant for Odoo, or remove it if it is a leftover
“the state file … is not a trustworthy source”	the manifest is not owned by root, or it lives in a directory writable by third parties	it drives destructive operations: fix its owner and permissions before using it

If the installation fails halfway

There is nothing to clean up by hand: the installer performs an automatic rollback and brings the system back to its initial state, with pre-existing resources left intact. Read the error in the log, fix the cause, and run it again: the installer resumes where it stopped, without redoing what was already done and without losing track of what it had created. Why that is safe: The rollback model.

Resuming needs the same parameters: with a different database name the installer stops and tells you which field does not match, rather than building a manifest straddling two instances.

If you would rather start from scratch: sudo invok rollback and then run it again, or --force.

If you interrupt with Ctrl-C

The installation undoes itself and the system returns to what it was: you have nothing to run. It takes effect between one step and the next — the one in progress is carried to completion, because stopping a package installation halfway would leave something worse than what you were avoiding.

A second Ctrl-C exits at once (code 130). There the system stays half-done by your choice, and sudo invok rollback cleans it up.

Risk-free preview

Before re-running, --dry-run shows what it would do without touching anything:

invok --config customer.env --dry-run