# 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:

```bash
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](/docs/fix-install-issues).

## 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](/docs/fix-llm-provider-errors).

## 4. Health Check Failures

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

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

Log locations and common startup failures are covered in [Installation Troubleshooting](/docs/fix-install-issues).

## 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

| Topic | Link |
|---|---|
| Installation Guide | /docs/install-chengos |
| Quickstart | /docs/quickstart-first-workflow |
| Installation Troubleshooting | /docs/fix-install-issues |
| LLM Provider Errors | /docs/fix-llm-provider-errors |
| FAQ | /docs/faq |
| Node Reference | /docs/nodes-input-output |
| Community MCP Access | /docs/community-mcp-access |

---

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.