> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.islo.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server. # Troubleshooting > Common problems when running the Islo CLI and how to fix them. For Line, Agent, Machine, trigger, or run failures, start with [factory troubleshooting](/operate/troubleshooting). This page covers CLI authentication, configuration, and direct sandbox use. 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: ```bash islo login ``` ### Not authenticated The CLI prints: ``` Not authenticated. Run 'islo login' or set ISLO_API_KEY environment variable. ``` For interactive use, run `islo login`. For CI or scripts: ```bash export ISLO_API_KEY=islo_key_… ``` Create keys with `islo api-key create` (see [API Keys](/cli/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: ```bash export ISLO_OAUTH_PORT=9999 islo login ``` ### `islo login --tool ` 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. Use `setup_script` or `setup_scripts` (see [Setup Scripts](/concepts/setup-scripts)). * `cpus:` — the field is `cpu` (singular). * A typo in any other field — check it against the [islo.yaml reference](/cli/islo-yaml). ### 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 ` does not re-execute them. Recreate the sandbox: ```bash islo rm my-sandbox -f islo use my-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: ```bash islo logs my-sandbox --type exec --since 30m ``` A failing `setup_script` will surface there. ### Connecting to a paused sandbox Paused sandboxes can resume automatically when `auto_resume` is `on_activity` on their [lifecycle policy](/concepts/sandbox-lifecycle). Otherwise, `islo use ` notices the paused state and prompts you to resume: ``` Sandbox 'my-sandbox' is paused. Resume? [y/N] ``` 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: ```bash islo resume my-sandbox ``` ### GitHub source configured but integration not connected When `sources:` points at GitHub and the GitHub integration isn't connected, the CLI warns: ``` GitHub source configured but GitHub integration not connected — cloning may fail for private repos. ``` Public repos still clone. For private repos: ```bash islo login --tool github ``` ## Agents ### `--task requires an agent profile with an entrypoint (use --agent)` `--task` is meaningful only with `--agent`. Re-run with both: ```bash islo use my-sandbox --agent claude --task "your prompt" ``` ### Agent starts but can't authenticate The agent provider isn't connected and no API key is in scope. Either connect the integration: ```bash islo login --tool anthropic # or: cursor, openai ``` …or pass the key via `--env`, `--env-file`, or `islo.yaml`'s `env:` section. ## Gateways ### Gateway profile reference fails `islo use --gateway-profile ` fails when the profile doesn't exist or you don't have access to it. List what's available: ```bash islo gateway ls ``` 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: ```bash islo gateway islo gateway rule ls ``` Add or update a rule with `add-rule` / `update-rule` (see [Gateways](/cli/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 '' was not found.` Exact message: ``` Port forward failed: sandbox '' was not found. Check `islo ls` for available sandboxes. (details: Sandbox '' not found). ``` 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: ``` $ curl http://localhost:3000 curl: (52) Empty reply from server ``` …or in a browser, *"the server unexpectedly dropped the connection"*. Resume the sandbox: ```bash islo resume my-sandbox ``` ### `Port forward failed: nothing is listening on port ` 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: ```bash islo ssh --setup ``` 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: ```bash islo update --version v0.21.0 ``` If you originally installed via `cargo install`, the auto-update path is skipped — use `cargo install` to update instead. ## Still stuck? Run: ```bash islo doctor --output json ``` …and include the output when you ask for help. It captures the most useful local state in one place.