Troubleshooting
Start with islo doctor whenever something looks wrong — it checks auth, configuration, and API connectivity in one shot. If that doesn’t surface the issue, look below.
Authentication
Token refresh failed / “Please login again with islo login”
Your refresh token is expired or invalid. Re-authenticate:
Not authenticated
The CLI prints:
For interactive use, run islo login. For CI or scripts:
Create keys with islo api-key create (see API Keys).
Browser doesn’t open during islo login
The CLI prints the URL it would have opened. Copy it into your browser manually — the local callback server keeps waiting on port 9876. If the port is busy:
islo login --tool <name> doesn’t complete
The web app integration page is polled for completion. If you closed the browser tab without finishing, just re-run the command. If the tool name is wrong, the CLI prints the list of valid providers.
islo.yaml
The YAML parser rejects a field
islo.yaml rejects unknown fields. Common causes:
tools:/tools_auto_detect:— these were removed. Usesetup_scriptorsetup_scripts(see Setup Scripts).cpus:— the field iscpu(singular).- A typo in any other field — check it against the islo.yaml reference.
YAML syntax errors
Errors that mention indentation, mappings, or unexpected tokens are surfaced verbatim by the YAML parser. Make sure you’re using spaces (not tabs) and that nested keys line up under their parent.
Setup script doesn’t run on an existing sandbox
setup_script / setup_scripts only run during sandbox creation. Editing them and running islo use <existing-name> does not re-execute them. Recreate the sandbox:
Sandboxes
”Sandbox not found”
islo ls only shows your own sandboxes by default — pass --all if you’re looking for a teammate’s. Soft-deleted ones surface with --status deleted.
Sandbox stays in starting or ends in failed
Check the setup logs:
A failing setup_script will surface there.
Connecting to a paused sandbox
islo use <paused-sandbox> notices the paused state and prompts you to resume:
Accept and the sandbox resumes automatically — no need to run islo resume first. If you want to resume in the background (e.g., before forwarding a port), use the explicit command:
GitHub source configured but integration not connected
When sources: points at GitHub and the GitHub integration isn’t connected, the CLI warns:
Public repos still clone. For private repos:
Agents
--task requires an agent profile with an entrypoint (use --agent)
--task is meaningful only with --agent. Re-run with both:
Agent starts but can’t authenticate
The agent provider isn’t connected and no API key is in scope. Either connect the integration:
…or pass the key via --env, --env-file, or islo.yaml’s env: section.
Gateways
Gateway profile reference fails
islo use --gateway-profile <name> fails when the profile doesn’t exist or you don’t have access to it. List what’s available:
Then verify spelling and use the exact name (or ID).
Request blocked / 403 from the gateway
A rule denied the request, or the profile’s --default-action is deny and no rule matched. Inspect the profile:
Add or update a rule with add-rule / update-rule (see Gateways).
Port forwarding
islo port-forward keeps running even if the remote side has problems — it tells you about each failure as connections come in, rather than exiting.
Port forward failed: sandbox '<name>' was not found.
Exact message:
The sandbox was deleted or renamed. Run islo ls (or islo ls --status deleted to see soft-deleted entries) and re-run with the correct name.
Connection drops with no response (empty reply)
When the sandbox is paused, the tunnel itself is up but the remote end has no process to answer. You’ll see things like:
…or in a browser, “the server unexpectedly dropped the connection”. Resume the sandbox:
Port forward failed: nothing is listening on port <N>
The sandbox is running but no process is bound to the port you forwarded to. Start the service inside the sandbox (islo use my-sandbox -- ./start.sh or via SSH) and retry.
Port forward failed: your session is not authorized anymore.
Your auth token expired mid-session. Run islo login and re-run the forward.
SSH
ssh my-sandbox.islo doesn’t connect
You probably haven’t run setup yet:
This writes the SSH config and certificate setup needed to reach *.islo hostnames.
Updates
islo update fails partway through
islo update downloads the install script from the releases server and runs it — the same path as a fresh install. A partial failure can leave the install half-applied. Retry the command. If the channel itself is stuck (network or release issue), pin to a known-good version:
If you originally installed via cargo install, the auto-update path is skipped — use cargo install to update instead.
Still stuck?
Run:
…and include the output when you ask for help. It captures the most useful local state in one place.
