Installation Problems

Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-12 ｜ Source: deploy/chengos.sh, deploy/.env.example, chengflow/docs/release-operations-guide.md

Almost every failed ChengOS install is one of four things: a port already in use, a database that will not connect, a placeholder secret left unchanged, or a path that means different things to two processes. Work through the triage below before reading further.

Triage

./chengos.sh status                      # processes, ports, version, health
curl http://127.0.0.1:19225/health        # is the API alive?
tail -n 100 deploy/logs/cheng-api.log    # why not?

status plus the API log identify the cause in most cases. Read the log from the top of the startup attempt, not the bottom — the first error is the cause and everything after it is consequence.

The API will not start

Port already in use

ss -tlnp | grep -E '19225|8080|5055|5432|6379|6333'

Either stop the conflicting process or change the port in deploy/.env (PORT/API_PORT, UI_PORT, APP_PORT). Remember that PORT and API_PORT both exist and should agree.

Database connection refused

pg_isready -h 127.0.0.1 -p 5432

Check in this order:

1. Are the databases running? ./chengos.sh status reports them.
2. Does DATABASE_URL use the right hostname for your mode? 127.0.0.1 for native and managed-process; postgres / redis / qdrant for Docker; your own host for distributed. This one mistake accounts for most "works natively, fails in Docker" reports.
3. Does the password inside DATABASE_URL match POSTGRES_PASSWORD? They are separate variables and they must agree.
4. Do the discrete DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD values agree with DATABASE_URL? Agent memory nodes read those instead of the URL, so a mismatch produces a system that starts fine and then fails only when a memory node runs.

Placeholder secrets

An install that still has template values will not work correctly:

grep -E 'replace_with|change_this' deploy/.env

Generate real values:

openssl rand -hex 32   # CREDENTIAL_MASTER_KEY_1, JWT_SECRET
openssl rand -hex 16   # POSTGRES_PASSWORD, REDIS_PASSWORD

Changing CREDENTIAL_MASTER_KEY_1 after credentials exist makes those credentials unreadable — set it before you store anything, and treat it as unrecoverable afterwards.

Migrations did not run

RUN_MIGRATIONS=true applies migrations at startup. If the schema looks empty, confirm it is set and, importantly, that CHENG_DEMO_MODE is not true — demo mode ignores RUN_MIGRATIONS entirely. A demo-mode install on a fresh database therefore has no schema and no way to create one, which is why demo mode must always be enabled after a normal initialization.

The UI loads but nothing works

The browser reaching the UI does not mean the UI can reach the API.

Open the browser console and network tab. Failing /api/v1/* requests point at:

• CORS. In production set CORS_PERMISSIVE=false and list real origins in CORS_ALLOWED_ORIGINS. A blocked request shows as a CORS error, not a 4xx.
• Wrong API URL. Check UI_API_BASE_URL and UI_WS_URL — normally /api/v1 and /ws behind one reverse proxy.
• BIND_ADDRESS inside Docker. It must be 0.0.0.0. Setting it to 127.0.0.1 inside the API container means the UI container cannot reach it — isolation comes from the host port binding, not from the bind address.
• WebSocket not proxied. Reverse proxies need explicit upgrade handling; REST working while live updates never arrive is the signature of this.

First-run setup problems

On a fresh database, GET /api/v1/auth/bootstrap-status returns needsSetup: true and the UI sends you to setup. If it does not:

• needsSetup: false on a database you believe is empty means you are pointed at a different database than you think.
• Registration refused means the deployment's registration policy or user limit applies.
• If demo mode is on, setup writes are blocked. Disable it, initialize, then re-enable.

CLI cannot connect

Remember the CLI's precedence order — flags, then environment, then config file, then defaults. A stale ~/.config/cheng/config.json silently overriding your intent is a common surprise.

Docker-specific

docker compose ps
docker compose logs api --tail=100

Update and rollback failures

Missing optional features

Some things are absent by configuration, not broken:

Verifying a release archive

./scripts/verify-release-archive.sh --archive PATH --expect-version 1.2.0
./scripts/check-release-consistency.sh --tag v1.2.0

Next steps

• Execution failures — when the install is fine but a run is not.
• Environment variable reference — every setting named above.
• Upgrades and rollback — update mechanics.