From 7dd2bc569fbf139d02717671235382335fe354c9 Mon Sep 17 00:00:00 2001 From: mamoodi Date: Thu, 12 Dec 2024 15:49:18 -0500 Subject: [PATCH] Restart troubleshooting documentation. (#5317) --- .../usage/troubleshooting/troubleshooting.md | 1 - .../current/usage/troubleshooting/windows.md | 66 ------ .../usage/troubleshooting/troubleshooting.md | 1 - .../current/usage/troubleshooting/windows.md | 66 ------ .../usage/how-to/persist-session-data.md | 16 ++ .../usage/troubleshooting/troubleshooting.md | 195 ++---------------- docs/modules/usage/troubleshooting/windows.md | 64 ------ docs/modules/usage/upgrade-guide.md | 71 ------- docs/sidebars.ts | 5 + 9 files changed, 41 insertions(+), 444 deletions(-) delete mode 100644 docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md delete mode 100644 docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md create mode 100644 docs/modules/usage/how-to/persist-session-data.md delete mode 100644 docs/modules/usage/troubleshooting/windows.md delete mode 100644 docs/modules/usage/upgrade-guide.md diff --git a/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/troubleshooting/troubleshooting.md b/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/troubleshooting/troubleshooting.md index 96e8bd58c0..2731b19904 100644 --- a/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/troubleshooting/troubleshooting.md +++ b/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/troubleshooting/troubleshooting.md @@ -9,7 +9,6 @@ Si vous trouvez plus d'informations ou une solution de contournement pour l'un d :::tip OpenHands ne prend en charge Windows que via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). Veuillez vous assurer d'exécuter toutes les commandes à l'intérieur de votre terminal WSL. -Consultez les [Notes pour les utilisateurs de WSL sur Windows](troubleshooting/windows) pour des guides de dépannage. ::: ## Problèmes courants diff --git a/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md b/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md deleted file mode 100644 index 467f9deb76..0000000000 --- a/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md +++ /dev/null @@ -1,66 +0,0 @@ - - -# Notes pour les utilisateurs de WSL sur Windows - -OpenHands ne prend en charge Windows que via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). -Veuillez vous assurer d'exécuter toutes les commandes dans votre terminal WSL. - -## Dépannage - -### Recommandation : Ne pas exécuter en tant qu'utilisateur root - -Pour des raisons de sécurité, il est fortement recommandé de ne pas exécuter OpenHands en tant qu'utilisateur root, mais en tant qu'utilisateur avec un UID non nul. - -Références : - -* [Pourquoi il est mauvais de se connecter en tant que root](https://askubuntu.com/questions/16178/why-is-it-bad-to-log-in-as-root) -* [Définir l'utilisateur par défaut dans WSL](https://www.tenforums.com/tutorials/128152-set-default-user-windows-subsystem-linux-distro-windows-10-a.html#option2) -Astuce concernant la 2ème référence : pour les utilisateurs d'Ubuntu, la commande pourrait en fait être "ubuntupreview" au lieu de "ubuntu". - ---- -### Erreur : 'docker' n'a pas pu être trouvé dans cette distribution WSL 2. - -Si vous utilisez Docker Desktop, assurez-vous de le démarrer avant d'appeler toute commande docker depuis WSL. -Docker doit également avoir l'option d'intégration WSL activée. - ---- -### Installation de Poetry - -* Si vous rencontrez des problèmes pour exécuter Poetry même après l'avoir installé pendant le processus de build, vous devrez peut-être ajouter son chemin binaire à votre environnement : - -```sh -export PATH="$HOME/.local/bin:$PATH" -``` - -* Si make build s'arrête sur une erreur comme celle-ci : - -```sh -ModuleNotFoundError: no module named -``` - -Cela pourrait être un problème avec le cache de Poetry. -Essayez d'exécuter ces 2 commandes l'une après l'autre : - -```sh -rm -r ~/.cache/pypoetry -make build -``` - ---- -### L'objet NoneType n'a pas d'attribut 'request' - -Si vous rencontrez des problèmes liés au réseau, tels que `NoneType object has no attribute 'request'` lors de l'exécution de `make run`, vous devrez peut-être configurer les paramètres réseau de WSL2. Suivez ces étapes : - -* Ouvrez ou créez le fichier `.wslconfig` situé à `C:\Users\%username%\.wslconfig` sur votre machine hôte Windows. -* Ajoutez la configuration suivante au fichier `.wslconfig` : - -```sh -[wsl2] -networkingMode=mirrored -localhostForwarding=true -``` - -* Enregistrez le fichier `.wslconfig`. -* Redémarrez complètement WSL2 en quittant toutes les instances WSL2 en cours d'exécution et en exécutant la commande `wsl --shutdown` dans votre invite de commande ou terminal. -* Après avoir redémarré WSL, essayez d'exécuter à nouveau `make run`. -Le problème de réseau devrait être résolu. diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/troubleshooting.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/troubleshooting.md index 30daa5e768..21514a594e 100644 --- a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/troubleshooting.md +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/troubleshooting.md @@ -7,7 +7,6 @@ :::tip OpenHands 仅通过 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) 支持 Windows。 请确保在您的 WSL 终端内运行所有命令。 -查看 [Windows 用户的 WSL 注意事项](troubleshooting/windows) 以获取一些故障排除指南。 ::: ## 常见问题 diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md deleted file mode 100644 index cb59ba2aee..0000000000 --- a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/troubleshooting/windows.md +++ /dev/null @@ -1,66 +0,0 @@ -以下是翻译后的内容: - -# 针对 Windows 上 WSL 用户的注意事项 - -OpenHands 仅通过 [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) 支持 Windows。 -请确保在您的 WSL 终端内运行所有命令。 - -## 故障排除 - -### 建议: 不要以 root 用户身份运行 - -出于安全原因,强烈建议不要以 root 用户身份运行 OpenHands,而是以具有非零 UID 的用户身份运行。 - -参考: - -* [为什么以 root 身份登录不好](https://askubuntu.com/questions/16178/why-is-it-bad-to-log-in-as-root) -* [在 WSL 中设置默认用户](https://www.tenforums.com/tutorials/128152-set-default-user-windows-subsystem-linux-distro-windows-10-a.html#option2) -关于第二个参考的提示:对于 Ubuntu 用户,命令实际上可能是 "ubuntupreview" 而不是 "ubuntu"。 - ---- -### 错误: 在此 WSL 2 发行版中找不到 'docker'。 - -如果您正在使用 Docker Desktop,请确保在从 WSL 内部调用任何 docker 命令之前启动它。 -Docker 还需要激活 WSL 集成选项。 - ---- -### Poetry 安装 - -* 如果您在构建过程中安装 Poetry 后仍然面临运行 Poetry 的问题,您可能需要将其二进制路径添加到环境中: - -```sh -export PATH="$HOME/.local/bin:$PATH" -``` - -* 如果 make build 在如下错误上停止: - -```sh -ModuleNotFoundError: no module named -``` - -这可能是 Poetry 缓存的问题。 -尝试依次运行这两个命令: - -```sh -rm -r ~/.cache/pypoetry -make build -``` - ---- -### NoneType 对象没有属性 'request' - -如果您在执行 `make run` 时遇到与网络相关的问题,例如 `NoneType 对象没有属性 'request'`,您可能需要配置 WSL2 网络设置。请按照以下步骤操作: - -* 在 Windows 主机上打开或创建位于 `C:\Users\%username%\.wslconfig` 的 `.wslconfig` 文件。 -* 将以下配置添加到 `.wslconfig` 文件中: - -```sh -[wsl2] -networkingMode=mirrored -localhostForwarding=true -``` - -* 保存 `.wslconfig` 文件。 -* 通过退出任何正在运行的 WSL2 实例并在命令提示符或终端中执行 `wsl --shutdown` 命令来完全重启 WSL2。 -* 重新启动 WSL 后,再次尝试执行 `make run`。 -网络问题应该得到解决。 diff --git a/docs/modules/usage/how-to/persist-session-data.md b/docs/modules/usage/how-to/persist-session-data.md new file mode 100644 index 0000000000..f079531498 --- /dev/null +++ b/docs/modules/usage/how-to/persist-session-data.md @@ -0,0 +1,16 @@ +# Persisting Session Data + +Using the standard installation, the session data is stored in memory. Currently, if OpenHands' service is restarted, +previous sessions become invalid (a new secret is generated) and thus not recoverable. + +## How to Persist Session Data + +### Development Workflow +In the `config.toml` file, specify the following: +``` +[core] +... +file_store="local" +file_store_path="/absolute/path/to/openhands/cache/directory" +jwt_secret="secretpass" +``` diff --git a/docs/modules/usage/troubleshooting/troubleshooting.md b/docs/modules/usage/troubleshooting/troubleshooting.md index f7787fc1b0..b117411b51 100644 --- a/docs/modules/usage/troubleshooting/troubleshooting.md +++ b/docs/modules/usage/troubleshooting/troubleshooting.md @@ -1,192 +1,37 @@ # 🚧 Troubleshooting -There are some error messages that frequently get reported by users. -We'll try to make the install process easier, but for now you can look for your error message below and see if there are any workarounds. -If you find more information or a workaround for one of these issues, please open a *PR* to add details to this file. - :::tip -OpenHands only supports Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). -Please be sure to run all commands inside your WSL terminal. -Check out [Notes for WSL on Windows Users](troubleshooting/windows) for some troubleshooting guides. +OpenHands only supports Windows via WSL. Please be sure to run all commands inside your WSL terminal. ::: -## Common Issues +### Launch docker client failed -* [Unable to connect to Docker](#unable-to-connect-to-docker) -* [404 Resource not found](#404-resource-not-found) -* [`make build` getting stuck on package installations](#make-build-getting-stuck-on-package-installations) -* [Sessions are not restored](#sessions-are-not-restored) -* [Connection to host.docker.internal timed out](#connection-to-host-docker-internal-timed-out) -* [Error building runtime docker image](#error-building-runtime-docker-image) +**Description** -### Unable to connect to Docker - -[GitHub Issue](https://github.com/All-Hands-AI/OpenHands/issues/1226) - -**Symptoms** - -```bash -Error creating controller. Please check Docker is running and visit `https://docs.all-hands.dev/modules/usage/troubleshooting` for more debugging information. +When running OpenHands, the following error is seen: +``` +Launch docker client failed. Please make sure you have installed docker and started docker desktop/daemon. ``` -```bash -docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory')) -``` - -**Details** - -OpenHands uses a Docker container to do its work safely, without potentially breaking your machine. - -**Workarounds** - -* Run `docker ps` to ensure that docker is running -* Make sure you don't need `sudo` to run docker [see here](https://www.baeldung.com/linux/docker-run-without-sudo) -* If you are on a Mac, check the [permissions requirements](https://docs.docker.com/desktop/mac/permission-requirements/) and in particular consider enabling the `Allow the default Docker socket to be used` under `Settings > Advanced` in Docker Desktop. -* In addition, upgrade your Docker to the latest version under `Check for Updates` +**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. --- -### `404 Resource not found` -**Symptoms** - -```python -Traceback (most recent call last): - File "/app/.venv/lib/python3.12/site-packages/litellm/llms/openai.py", line 414, in completion - raise e - File "/app/.venv/lib/python3.12/site-packages/litellm/llms/openai.py", line 373, in completion - response = openai_client.chat.completions.create(**data, timeout=timeout) # type: ignore - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - File "/app/.venv/lib/python3.12/site-packages/openai/_utils/_utils.py", line 277, in wrapper - return func(*args, **kwargs) - ^^^^^^^^^^^^^^^^^^^^^ - File "/app/.venv/lib/python3.12/site-packages/openai/resources/chat/completions.py", line 579, in create - return self._post( - ^^^^^^^^^^^ - File "/app/.venv/lib/python3.12/site-packages/openai/_base_client.py", line 1232, in post - return cast(ResponseT, self.request(cast_to, opts, stream=stream, stream_cls=stream_cls)) - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - File "/app/.venv/lib/python3.12/site-packages/openai/_base_client.py", line 921, in request - return self._request( - ^^^^^^^^^^^^^^ - File "/app/.venv/lib/python3.12/site-packages/openai/_base_client.py", line 1012, in _request - raise self._make_status_error_from_response(err.response) from None -openai.NotFoundError: Error code: 404 - {'error': {'code': '404', 'message': 'Resource not found'}} -``` - -**Details** - -This happens when LiteLLM (our library for connecting to different LLM providers) can't find -the API endpoint you're trying to connect to. Most often this happens for Azure or ollama users. - -**Workarounds** - -* Check that you've set `LLM_BASE_URL` properly -* Check that the model is set properly, based on the [LiteLLM docs](https://docs.litellm.ai/docs/providers) - * If you're running inside the UI, be sure to set the `model` in the settings modal - * If you're running headless (via main.py) be sure to set `LLM_MODEL` in your env/config -* Make sure you've followed any special instructions for your LLM provider - * [Azure](/modules/usage/llms/azure-llms) - * [Google](/modules/usage/llms/google-llms) -* Make sure your API key is correct -* See if you can connect to the LLM using `curl` -* Try [connecting via LiteLLM directly](https://github.com/BerriAI/litellm) to test your setup - ---- -### `make build` getting stuck on package installations - -**Symptoms** - -Package installation stuck on `Pending...` without any error message: - -```bash -Package operations: 286 installs, 0 updates, 0 removals - - - Installing certifi (2024.2.2): Pending... - - Installing h11 (0.14.0): Pending... - - Installing idna (3.7): Pending... - - Installing sniffio (1.3.1): Pending... - - Installing typing-extensions (4.11.0): Pending... -``` - -**Details** - -In rare cases, `make build` can seemingly get stuck on package installations -without any error message. - -**Workarounds** - -The package installer Poetry may miss a configuration setting for where credentials are to be looked up (keyring). - -First check with `env` if a value for `PYTHON_KEYRING_BACKEND` exists. -If not, run the below command to set it to a known value and retry the build: - -```bash -export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring -``` - ---- -### Sessions are not restored - -**Symptoms** - -OpenHands usually asks whether to resume or start a new session when opening the UI. -But clicking "Resume" still starts a fresh new chat. - -**Details** - -With a standard installation as of today session data is stored in memory. -Currently, if OpenHands's service is restarted, previous sessions become -invalid (a new secret is generated) and thus not recoverable. - -**Workarounds** - -* Change configuration to make sessions persistent by editing the `config.toml` -file (in OpenHands's root folder) by specifying a `file_store` and an -absolute `file_store_path`: - -```toml -file_store="local" -file_store_path="/absolute/path/to/openhands/cache/directory" -``` - -* Add a fixed jwt secret in your .bashrc, like below, so that previous session id's -should stay accepted. - -```bash -EXPORT JWT_SECRET=A_CONST_VALUE -``` - ---- -### Connection to host docker internal timed out - -**Symptoms** - -When you start the server using the docker command from the main [README](https://github.com/All-Hands-AI/OpenHands/README.md), you get a long timeout -followed by the a stack trace containing messages like: - -* `Connection to host.docker.internal timed out. (connect timeout=310)` -* `Max retries exceeded with url: /alive` - -**Details** - -If Docker Engine is installed rather than Docker Desktop, the main command will not work as expected. -Docker Desktop includes easy DNS configuration for connecting processes running in different containers -which OpenHands makes use of when the main server is running inside a docker container. -(Further details: https://forums.docker.com/t/difference-between-docker-desktop-and-docker-engine/124612) - -**Workarounds** - -* [Install Docker Desktop](https://www.docker.com/products/docker-desktop/) -* Run OpenHands in [Development Mode](https://github.com/All-Hands-AI/OpenHands/blob/main/Development.md), - So that the main server is not run inside a container, but still creates dockerized runtime sandboxes. - ---- +# Development Workflow Specific ### Error building runtime docker image -**Symptoms** -Attempts to start a new session fail, and an errors with terms like the following appear in the logs: -* `debian-security bookworm-security` -* `InRelease At least one invalid signature was encountered.` +**Description** + +Attempts to start a new session fail, and errors with terms like the following appear in the logs: +``` +debian-security bookworm-security +InRelease At least one invalid signature was encountered. +``` This seems to happen when the hash of an existing external library changes and your local docker instance has cached a previous version. To work around this, please try the following: diff --git a/docs/modules/usage/troubleshooting/windows.md b/docs/modules/usage/troubleshooting/windows.md deleted file mode 100644 index c0196b7513..0000000000 --- a/docs/modules/usage/troubleshooting/windows.md +++ /dev/null @@ -1,64 +0,0 @@ -# Notes for WSL on Windows Users - -OpenHands only supports Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). -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. - -References: - -* [Why it is bad to login as root](https://askubuntu.com/questions/16178/why-is-it-bad-to-log-in-as-root) -* [Set default user in WSL](https://www.tenforums.com/tutorials/128152-set-default-user-windows-subsystem-linux-distro-windows-10-a.html#option2) -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. - ---- -### 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: - -```sh -export PATH="$HOME/.local/bin:$PATH" -``` - -* If make build stops on an error like this: - -```sh -ModuleNotFoundError: no module named -``` - -This could be an issue with Poetry's cache. -Try to run these 2 commands after another: - -```sh -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: - -```sh -[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. diff --git a/docs/modules/usage/upgrade-guide.md b/docs/modules/usage/upgrade-guide.md deleted file mode 100644 index 01e68d558b..0000000000 --- a/docs/modules/usage/upgrade-guide.md +++ /dev/null @@ -1,71 +0,0 @@ -# ⬆️ Upgrade Guide - -## 0.8.0 (2024-07-13) - -### Config breaking changes - -In this release we introduced a few breaking changes to backend configurations. -If you have only been using OpenHands via frontend (web GUI), nothing needs -to be taken care of. - -Here's a list of breaking changes in configs. They only apply to users who -use OpenHands CLI via `main.py`. For more detail, see [#2756](https://github.com/All-Hands-AI/OpenHands/pull/2756). - -#### Removal of --model-name option from main.py - -Please note that `--model-name`, or `-m` option, no longer exists. You should set up the LLM -configs in `config.toml` or via environmental variables. - -#### LLM config groups must be subgroups of 'llm' - -Prior to release 0.8, you can use arbitrary name for llm config in `config.toml`, e.g. - -```toml -[gpt-4o] -model="gpt-4o" -api_key="" -``` - -and then use `--llm-config` CLI argument to specify the desired LLM config group -by name. This no longer works. Instead, the config group must be under `llm` group, -e.g.: - -```toml -[llm.gpt-4o] -model="gpt-4o" -api_key="" -``` - -If you have a config group named `llm`, no need to change it, it will be used -as the default LLM config group. - -#### 'agent' group no longer contains 'name' field - -Prior to release 0.8, you may or may not have a config group named `agent` that -looks like this: - -```toml -[agent] -name="CodeActAgent" -memory_max_threads=2 -``` - -Note the `name` field is now removed. Instead, you should put `default_agent` field -under `core` group, e.g. - -```toml -[core] -# other configs -default_agent='CodeActAgent' - -[agent] -llm_config='llm' -memory_max_threads=2 - -[agent.CodeActAgent] -llm_config='gpt-4o' -``` - -Note that similar to `llm` subgroups, you can also define `agent` subgroups. -Moreover, an agent can be associated with a specific LLM config group. For more -detail, see the examples in `config.template.toml`. diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 5bc5e767bc..436bd63e90 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -121,6 +121,11 @@ const sidebars: SidebarsConfig = { label: 'Custom Sandbox', id: 'usage/how-to/custom-sandbox-guide', }, + { + type: 'doc', + label: 'Persist Session Data', + id: 'usage/how-to/persist-session-data', + }, ], }, {