# Star Office Troubleshooting

## 1. `Unauthorized` on `127.0.0.1:<port>`

Common causes:

- Backend started but session/auth state not initialized.
- Opened backend port directly instead of frontend port.
- `state.json` missing or invalid.

Actions:

1. Ensure `state.json` exists (copy from `state.sample.json` if needed).
2. Start backend with venv Python:
   - `cd backend && ../.venv/bin/python app.py`
3. Open frontend URL (usually `http://127.0.0.1:19000`) instead of backend API port.
4. Run `bash skills/star-office-helper/scripts/star_office_doctor.sh` and check port + HTTP status.

## 2. `pip install` fails with `externally-managed-environment`

Cause:

- macOS/Homebrew Python follows PEP 668 and blocks system-wide pip write.

Fix:

1. `python3 -m venv .venv`
2. `.venv/bin/python -m pip install --upgrade pip`
3. `.venv/bin/python -m pip install -r backend/requirements.txt`

Avoid:

- `--break-system-packages` unless user explicitly requires system install.

## 3. Nomi connected but preview does not move

Cause:

- Nomi can talk to OpenClaw, but Star Office is only a visualization layer.
- No event bridge from OpenClaw task stream to Star Office backend.
- Wrong preview URL.

Checklist:

1. Confirm Star Office frontend port (default `19000`) is reachable.
2. Confirm backend is running and receiving events.
3. Confirm Nomi preview panel URL exactly matches frontend URL.
4. Trigger a real OpenClaw task and observe backend logs.

## 4. Port confusion (`18791` vs `19000`)

Typical mapping:

- `18791`: backend/service/auth endpoint (may return `Unauthorized`).
- `19000`: frontend visual UI for browser preview.

Rule:

- In Nomi preview panel, use frontend URL.