Troubleshooting

Each symptom of a local run with entirius-zeno comes with its cause and the fix. Running the stack needs no private access: the one part that does, the AI toolbox, is switched off by default.

Quick Run

make dev finished, but the API does not answer

Cause: make dev exits 0 even when the service failed to start.

Fix: run make status to see which containers are up, then make logs and read the service log. The error is there.

The seed stopped

Cause: a seed step failed. The output ends with SEED FAILED (exit N) during: <step>, which names the phase.

Fix: fix what the named step reports, then run make seed again.

The storefront lists fewer products than the seed imported

Cause: on the first service version of Platform 4.0, two fills of the storefront read model that overlapped on one channel during a seed or a large import deleted each other’s rows. The catalog in the CMS is complete; only the storefront copy is short. The patch of 2026-10-13 fixes it (Release Notes); it does not bring back rows that are already gone.

Fix: move to the patched service version, then rebuild the read model once. Run make shell, then:

python manage.py fill-read-model

The dashboard says baked mode right after a dev start

Cause: the service environment is still syncing, so the dashboard was generated too early.

Fix: run make dashboard again.

Seeding or tests cannot find the test package

Cause: the test package was cloned after make up. Its checkout is bind-mounted into the containers when they start.

Fix: run make clone-tests before make up. If the stack is already running, clone, then restart it.

The storefront still uses the old API port or channel

Cause: the storefront configuration is baked in when its image is built.

Fix: run make pwa again after changing SERVICE_PORT or PWA_CHANNEL.

A port is already in use

Cause: the harness publishes PostgreSQL, Redis, RabbitMQ and the backend on their standard ports +100, so that local instances on the standard ports keep running. Another process holds one of the published ports.

Fix: set another value in .env for the variable that docker-compose.yml names for that port, for example SERVICE_PORT or POSTGRES_PORT, and start the stack again. make urls prints the ports in use.

make e2e fails before the first test

Cause: the Playwright browser is not installed on the host.

Fix: install it once on the host. The e2e run is described in the harness testing guide.

cd repos/tests/entirius-test-package-emporium && uv run --extra e2e playwright install chromium

AI actions are disabled in the CMS, AI scenarios are skipped

Cause: the AI toolbox is switched off. .env.example ships AI_TOOLBOX_ENABLED=0, and the toolbox status is disabled. This is the default and nothing is broken: the catalog, the CMS, the storefront, checkout and the seed work. AI drafts, lead intel and translations are off, the translation endpoints answer 503 AI_TOOLBOX_DISABLED, and make bdd skips the scenarios tagged @needs-toolbox.

Fix: none needed. The toolbox is not public. With credentials from the Entirius team, set AI_TOOLBOX_ENABLED=1, AI_TOOLBOX_BASE_URL, AI_TOOLBOX_API_KEY and AI_TOOLBOX_CHANNEL in .env, run make dev so the containers get the new values (a restart keeps the old ones), then run make toolbox-check. A status of unconfigured means the toolbox is enabled without those settings.

make check fails in a module clone

Cause: the target also checks for the maintainers’ private secret-scanning configuration, which a public clone does not have.

Fix: run the checks it wraps directly. The contributor path is in Secret Scanning.

Sign-in answers 429 after a few wrong passwords

Cause: with the access module installed, ten failed logins for one user from one address on api/token/ block that user from that address for 15 minutes. A script that probes with a stale password locks admin out of the CMS and the tests too.

Fix: stop the script, wait until the block ends, then sign in with the right password.

A changed ACCESS_GATE_MODE has no effect

Cause: the mode reaches the service from .env through compose, and a container restart keeps the old environment.

Fix: run make dev again. It starts the service with the new value.

A generate-api-key command answers Keys are access tokens now

Cause: with the access module installed, API keys are application tokens and the per-module key commands refuse.

Fix: create a token instead. The raw value is printed once:

manage.py access_token create --application <name> --create-application --scope <scope>

Add --channel <idx> to pin the token to one channel, as the refusal message shows. Scopes and how a token is sent: Access and API Tokens.

Next

Quickstart