> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

<Tip>
  OpenHands only supports Windows via WSL. Please be sure to run all commands inside your WSL terminal.
</Tip>

### Launch docker client failed

**Description**

When running OpenHands, the following error is seen:

```
Launch docker client failed. Please make sure you have installed docker and started docker desktop/daemon.
```

**Resolution**

Try these in order:

* Confirm `docker` is running on your system. You should be able to run `docker ps` in the terminal successfully.
* If using Docker Desktop, ensure `Settings > Advanced > Allow the default Docker socket to be used` is enabled.
* Depending on your configuration you may need `Settings > Resources > Network > Enable host networking` enabled in Docker Desktop.
* Reinstall Docker Desktop.

### Permission Error

**Description**

On initial prompt, an error is seen with `Permission Denied` or `PermissionError`.

**Resolution**

* Check if the `~/.openhands` is owned by `root`. If so, you can:
  * Change the directory's ownership: `sudo chown <user>:<user> ~/.openhands`.
  * or update permissions on the directory: `sudo chmod 777 ~/.openhands`
  * or delete it if you don’t need previous data. OpenHands will recreate it. You'll need to re-enter LLM settings.
* If mounting a local directory, ensure your `WORKSPACE_BASE` has the necessary permissions for the user running
  OpenHands.

### On Linux, Getting ConnectTimeout Error

**Description**

When running on Linux, you might run into the error `ERROR:root:<class 'httpx.ConnectTimeout'>: timed out`.

**Resolution**

If you installed Docker from your distribution’s package repository (e.g., docker.io on Debian/Ubuntu), be aware that
these packages can sometimes be outdated or include changes that cause compatibility issues. try reinstalling Docker
[using the official instructions](https://docs.docker.com/engine/install/) to ensure you are running a compatible version.

If that does not solve the issue, try incrementally adding the following parameters to the docker run command:

* `--network host`
* `-e SANDBOX_USE_HOST_NETWORK=true`
* `-e DOCKER_HOST_ADDR=127.0.0.1`

### Internal Server Error. Ports are not available

**Description**

When running on Windows, the error `Internal Server Error ("ports are not available: exposing port TCP
...: bind: An attempt was made to access a socket in a
way forbidden by its access permissions.")` is encountered.

**Resolution**

* Run the following command in PowerShell, as Administrator to reset the NAT service and release the ports:

```
Restart-Service -Name "winnat"
```

### Unable to access VS Code tab via local IP

**Description**

When accessing OpenHands through a non-localhost URL (such as a LAN IP address), the VS Code tab shows a "Forbidden"
error, while other parts of the UI work fine.

**Resolution**

This happens because VS Code runs on a random high port that may not be exposed or accessible from other machines.
To fix this:

1. Set a specific port for VS Code using the `SANDBOX_VSCODE_PORT` environment variable:

   ```bash theme={null}
   docker run -it --rm \
       -e SANDBOX_VSCODE_PORT=41234 \
       -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
       -e AGENT_SERVER_IMAGE_TAG=1.19.1-python \
       -v /var/run/docker.sock:/var/run/docker.sock \
       -v ~/.openhands:/.openhands \
       -p 3000:3000 \
       -p 41234:41234 \
       --add-host host.docker.internal:host-gateway \
       --name openhands-app \
       docker.openhands.dev/openhands/openhands:latest
   ```

   > **Note**: If you used OpenHands before version 0.44, you may want to run `mv ~/.openhands-state ~/.openhands` to migrate your conversation history to the new location.

2. Make sure to expose the same port with `-p 41234:41234` in your Docker command.

3. If running with the development workflow, you can set this in your `config.toml` file:
   ```toml theme={null}
   [sandbox]
   vscode_port = 41234
   ```

### User Skills Not Loading in Docker

**Description**

When running OpenHands via Docker, custom skills placed in `~/.openhands/skills/` or `~/.agents/skills/` on the host
machine are not loaded. The skill loader logs show `'user': 0`.

**Resolution**

The agent-server container cannot see your host filesystem by default. Mount your local skills directory into the
sandbox using the `SANDBOX_VOLUMES` environment variable:

```bash theme={null}
-e SANDBOX_VOLUMES="$HOME/.agents/skills:/home/openhands/.agents/skills:ro"
```

<Note>
  Mount into `~/.agents/skills` inside the container, not `~/.openhands/skills`. The latter would overwrite
  the public skills cache and prevent built-in skills from loading.
</Note>

See [User Skills When Running OpenHands on Your Own](/overview/skills/org#user-skills-when-running-openhands-on-your-own) for the full Docker command.

### GitHub Organization Rename Issues

**Description**

After the GitHub organization rename from `All-Hands-AI` to `OpenHands`, you may encounter issues with git remotes, Docker images, or broken links.

**Resolution**

* Update your git remote URL:
  ```bash theme={null}
  # Check current remote
  git remote get-url origin

  # Update SSH remote
  git remote set-url origin git@github.com:OpenHands/OpenHands.git

  # Or update HTTPS remote
  git remote set-url origin https://github.com/OpenHands/OpenHands.git
  ```
* Update Docker image references from `ghcr.io/all-hands-ai/` to `ghcr.io/openhands/`
* Find and update any hardcoded references:
  ```bash theme={null}
  git grep -i "all-hands-ai"
  git grep -i "ghcr.io/all-hands-ai"
  ```