mirror of
https://github.com/OpenHands/OpenHands.git
synced 2025-12-26 05:48:36 +08:00
100 lines
3.3 KiB
Plaintext
100 lines
3.3 KiB
Plaintext
---
|
||
title: 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**
|
||
|
||
* Add the `--network host` to the docker run command.
|
||
|
||
### 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
|
||
docker run -it --rm \
|
||
-e SANDBOX_VSCODE_PORT=41234 \
|
||
-e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:latest \
|
||
-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.all-hands.dev/all-hands-ai/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
|
||
[sandbox]
|
||
vscode_port = 41234
|
||
```
|