Skip to content

Troubleshooting.md

Latest commit

 

History

History
119 lines (81 loc) · 2.7 KB

Troubleshooting.md

File metadata and controls

119 lines (81 loc) · 2.7 KB

Troubleshooting

Use this page when Coder Studio does not start, cannot reach a provider, or cannot be opened from another device.

First-Run Checklist

If the first trial does not work, check in this order:

  1. node --version confirms Node.js >= 24.0.0.
  2. coder-studio version confirms the CLI is installed.
  3. coder-studio status confirms the service is running.
  4. coder-studio logs shows recent errors.
  5. which <provider-command> confirms the Provider CLI is in PATH.
  6. <provider-command> --version confirms the Provider CLI can run.
  7. If the browser does not open, manually visit the URL from coder-studio status.
  8. If mobile cannot connect, confirm the service listens on 0.0.0.0 and your firewall allows the port.

Use desktop for the first full trial. Do not start by debugging public tunnels and phone access at the same time.

Coder Studio Does Not Start

Check status and logs:

coder-studio status
coder-studio logs

Try foreground mode for a direct error:

coder-studio serve --foreground

Browser Did Not Open

Run:

coder-studio status

Open the displayed URL manually.

Port Is Already In Use

Change the port and restart:

coder-studio config --port 8080
coder-studio serve --restart

Provider Is Missing

Coder Studio can open files and terminals without an AI CLI, but agent sessions require their matching provider CLIs.

Install the provider CLI, confirm it works in a normal terminal, then start a new session in Coder Studio.

Phone Cannot Open The Workspace

Common causes:

  • Phone and computer are not on the same network.
  • Wi-Fi guest isolation blocks device-to-device access.
  • The computer firewall blocks the port.
  • Coder Studio is listening only on localhost.
  • VPN, company network, or campus network blocks local device discovery.

For LAN access:

coder-studio config --host 0.0.0.0
coder-studio serve --restart
coder-studio status

Then open:

http://<computer-lan-ip>:<port>

Login Or Password Problems

Reset the password:

coder-studio config --password <new-strong-password>
coder-studio serve --restart

If an IP is blocked after repeated failed attempts:

coder-studio auth ban-list
coder-studio auth unblock --ip <ip-address>

WebSocket Or Connection Issues

Try:

  • Refreshing the browser.
  • Checking coder-studio status.
  • Checking coder-studio logs.
  • Confirming the tunnel or network route is still active.
  • Restarting the service with coder-studio serve --restart.

Still Stuck

Collect:

  • coder-studio status
  • Relevant coder-studio logs
  • Browser URL used
  • Operating system
  • Node.js version
  • Whether the issue happens locally, on LAN, or through a tunnel