Troubleshooting and Logging
Almost everything zCICD does happens in a background job. When something did not happen, the question is nearly always which job failed, and what did it say — not what does the Odoo error log show.
This page covers where to look, in the order worth looking.
1. The branch's Tasks tab
A Task is one unit of work on an instance: a build, a restore, a module update, a restart. Pressing a button on a branch creates a task.
Open the branch and look at Tasks. Each task records:
| Field | Meaning |
|---|---|
| State | Pending, done or failed |
| Queue position | Where it sits in the queue if not started |
| Duration | How long it took |
| Log | The full output of the work |
| Dump used | Which dump a restore consumed |
| Machine | Where it ran |
A task stuck in pending with a queue position is waiting, not broken. A task in failed has its reason in Log.
Tasks are visible under the top-level Tasks menu too, across all branches — useful when you want to know whether the whole system is backed up rather than one branch.
2. Queue jobs
Tasks are executed as queue jobs. When a task never even starts, the queue is the next place to look.
zCICD runs queue jobs in dedicated channels — the recommended configuration splits test runs from everything else, so a long test run cannot starve ordinary work:
ODOO_QUEUEJOBS_CHANNELS=testruns:5,others:10
A release item exposes Failed Jobs directly on its form; a non-zero count is almost always why an item is stuck. Test runs expose their queue jobs the same way, and Rerun on a test run deletes its jobs and starts over.
3. Live Logs and log lines
The Logging menu (manager-only) has two entries:
- Live Logs — a live view of what zCICD is doing right now
- Stored log lines
Log lines are structured rather than free text, which makes them searchable:
| Field | Use |
|---|---|
| Level | Info, Warning, Error, Debug |
| Source | Which subsystem emitted it |
| Project | Which instance it belongs to |
| Date | Indexed, so time-ranged searches are fast |
Lines are linked to the task, instance, repository or release item they came from, so you can start at a failure and pivot to everything logged around it.
4. Container logs
Two different things are called logs, and mixing them up wastes time:
Instance containers. The Logs action on a branch (Developer role) opens live logs for that instance's containers. This is where an Odoo traceback lives.
zCICD's own containers. Configuration > CICD Container shows logs for zCICD itself:
| Container | What it is |
|---|---|
| Queuejobs | The queue job runner |
| Cronjobs | Scheduled actions |
| Delegator | Request routing to instances |
| CICD Postgres | zCICD's own database |
Set Log Lines to control how much is fetched — the default is 100.
If instances are not being built at all, or nothing is being scheduled, look at Queuejobs and Cronjobs here rather than at any individual branch.
Common situations
An instance is unavailable
Nearly always crashed containers. Work up in this order:
- Restart — restarts the containers. Fixes most cases.
- Reload — regenerates the Docker configuration from current source.
- Build — rebuilds images and reinstalls packages.
- Open the instance Logs and read the actual error.
Covered in more detail in Your First Branch.
A branch never got an instance
Check, in order:
- Does the repository have Initialize new Branches enabled?
- Has a fetch happened since the branch was pushed? Use Fetch all Branches on the repository.
- Is the branch a release branch? Those are excluded from automatic preparation.
- Was the branch deactivated by cleanup? Clear the Active filter.
An instance stopped on its own
Expected behaviour after an hour of inactivity — see Instance Lifecycle. Raise Cycle Down After Seconds if you need it up longer.
Odoo Login offers stale users
The cached user list is out of date, usually after a reset or restore. Press Update Users and wait for the sync task to finish.
Broken CSS or JavaScript
Run Remove Web Assets. It stops Odoo, removes the generated bundles and starts it again; assets regenerate on next login. If a restore caused it, check the repository's Remove Webassets setting.
A release item is stuck
Look at Failed Jobs on the item first, then its Log and Exception Info. States starting with Collecting mean it is still gathering branches; Integration means it has closed collection and is merging. See Releases.
Tests all report Reused and nothing ran
Intended: nothing relevant changed. Tick No Reuse on the test run to force a full execution. See Test Runs.
A volume filled up
Builds fail in confusing ways when a source volume is full. Check volume usage under Configuration > Machines, and set Warn below percent so it is caught earlier. Free Volumes (down -v) on idle instances reclaims space, as does letting cleanup deactivate untouched branches.
Escalation order
When you have no idea where to start:
- Branch Tasks tab — did the work run and fail?
- Instance Logs — did Odoo itself error?
- Logging > Live Logs — is zCICD doing anything at all?
- Configuration > CICD Container — are the queue and cron runners alive?
- Volume usage — is the machine out of disk?