Troubleshooting

Start with the host report

Run doctor in the actual host terminal, inside WSL2/Lima/PRoot when relevant. It reports supported capabilities and setup errors. Use the report to distinguish runtime, provider and device problems.

mso doctor
mso --version

mso: command not found

Open a fresh terminal after installation. On POSIX hosts, refresh ~/.local/bin in this shell. On Windows, enter the selected WSL2 distro first.

export PATH="$HOME/.local/bin:$HOME/.bun/bin:$PATH"
command -v mso

Browser cannot reach the workspace

Run mso web on the host and verify its local health endpoint. Default port is 4005; use the configured port if you changed it.

If local health works but a remote hostname fails, inspect that hostname’s DNS, HTTPS proxy/tunnel and origin reachability separately.

mso web
# In another host terminal:
curl -fsS http://127.0.0.1:4005/api/health

Pending approval or repeated login

Approve the exact device on the final browser origin. Remote plain HTTP cannot retain MSO’s Secure cookie. Use localhost or protected HTTPS and stay on the same URL.

Supported local repair

Doctor’s fix mode repairs safe local issues. It does not change your DNS, firewall, TLS or public exposure. If build/update is incomplete, use the updater’s status/log instead of deleting state.

mso doctor --fix
mso doctor
mso update status

Cloudflare 522

A 522 means Cloudflare could not establish or complete the connection to its configured origin. Check the actual DNS record target, listener/firewall and proxy/tunnel on that origin.

The MSO product website is served independently from installed hosts. A healthy public landing is not a health check for your own instance.