Can't Install? Start Here: ChengOS Installation Troubleshooting Guide (Continuously Updated)

Can't Install? Start Here: ChengOS Installation Troubleshooting Guide

Having trouble installing or first-run issues? Don't worry — 90% of problems fall into the four categories below. Spend 2 minutes matching your symptom, and you can probably fix it yourself. If not, post a question using the template at the end and you'll get a faster reply.

30-Second Pre-Check

Before posting or digging deeper, confirm:

• Your ChengOS version (from the installer output or cheng --version)
• Deployment mode: Docker or native binary?
• OS and architecture (e.g. Ubuntu 22.04 / x86_64)
• Available memory (on 512MB machines use the native binary — do not install Docker)
• The full error message (screenshot or text — "it failed" is not enough)

1. Port Already in Use

Typical errors: Address already in use, service exits immediately after starting.

ChengOS uses ports 8080 (API), 5173 (UI dev), 3000 (App) by default. To check:

sudo lsof -i :8080
sudo ss -tlnp | grep 8080

Fix: stop the conflicting process, or change the port in your config and restart. See Installation Troubleshooting.

2. Docker Permission / Image Pull Failures

Typical errors: permission denied (docker.sock), pull access denied, or pull timeouts.

• Permission: add your user to the docker group (sudo usermod -aG docker $USER) and log in again
• Pull timeouts: usually network-related; configure a registry mirror
• Under 1GB RAM: strongly consider the native binary install — Docker alone consumes several hundred MB

3. LLM Provider Errors

Typical errors: 401 Unauthorized, model not found, connection timeouts.

• Is the API key correct and stored in the credential vault?
• Does the model name match the provider's docs exactly (case-sensitive)?
• Accessing OpenAI etc. from restricted regions requires a proxy

See LLM Provider Troubleshooting.

4. Health Check Failures

When the UI won't load or the CLI can't connect:

curl http://localhost:8080/healthz
# check logs to locate the cause

Log locations and common startup failures are covered in Installation Troubleshooting.

Help-Request Template

If none of the above solves it, include this when posting:

- Version:
- Deployment mode: Docker / native binary
- OS:
- What I did:
- Expected result:
- Actual result / error message:

Documentation Map

This post is continuously updated. If you hit a pitfall not listed here, please reply and share it — your experience will help the next person installing ChengOS.