OpenHands/docs/modules/usage/troubleshooting/windows.md

Notes for Windows and WSL Users

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

Troubleshooting

Recommendation: Do not run as root user

For security reasons, it is highly recommended to not run OpenHands as the root user, but a user with a non-zero UID. In addition, persistent sandboxes won't be supported when running as root and during start of OpenHands an appropriate message may appear.

References:

• Why it is bad to login as root
• Set default user in WSL
  Hint about the 2nd reference: for Ubuntu users, the command could actually be "ubuntupreview" instead of "ubuntu".

---

Error: 'docker' could not be found in this WSL 2 distro.

If you are using Docker Desktop, make sure to start it before calling any docker command from inside WSL. Docker also needs to have the WSL integration option activated.

---

Failed to create openhands user

If you encounter the following error during setup:

Exception: Failed to create openhands user in sandbox: 'useradd: UID 0 is not unique'

You can resolve it by running:

export SANDBOX_USER_ID=1000

---

Poetry Installation

• If you face issues running Poetry even after installing it during the build process, you may need to add its binary path to your environment:

export PATH="$HOME/.local/bin:$PATH"

• If make build stops on an error like this:

ModuleNotFoundError: no module named <module-name>

This could be an issue with Poetry's cache. Try to run these 2 commands after another:

rm -r ~/.cache/pypoetry
make build

---

NoneType object has no attribute 'request'

If you are experiencing issues related to networking, such as NoneType object has no attribute 'request' when executing make run, you may need to configure your WSL2 networking settings. Follow these steps:

• Open or create the .wslconfig file located at C:\Users\%username%\.wslconfig on your Windows host machine.
• Add the following configuration to the .wslconfig file:

[wsl2]
networkingMode=mirrored
localhostForwarding=true

• Save the .wslconfig file.
• Restart WSL2 completely by exiting any running WSL2 instances and executing the command wsl --shutdown in your command prompt or terminal.
• After restarting WSL, attempt to execute make run again.
  The networking issue should be resolved.