Add troubleshooting document and issue template (All-Hands-AI#1243)

* add troubleshooting doc * add link to troubleshooting * mark required * unmark required * more required stuff * add nonetype issue * Update .github/ISSUE_TEMPLATE/bug_template.yml Co-authored-by: Boxuan Li <[email protected]> * Update .github/ISSUE_TEMPLATE/bug_template.yml --------- Co-authored-by: Boxuan Li <[email protected]>
haoyaogang · Apr 20, 2024 · 3c85ece · 3c85ece
1 parent 0356f6e
commit 3c85ece
Show file tree

Hide file tree

Showing 4 changed files with 143 additions and 42 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
diff --git a/.github/ISSUE_TEMPLATE/bug_template.yml b/.github/ISSUE_TEMPLATE/bug_template.yml
@@ -0,0 +1,69 @@
+name: Bug
+description: Report a problem with OpenDevin
+title: '[Bug]: '
+labels: ['bug']
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for taking the time to fill out this bug report. We greatly appreciate your effort to complete this template fully. Please provide as much information as possible to help us understand and address the issue effectively.
+
+  - type: checkboxes
+    attributes:
+      label: Is there an existing issue for the same bug?
+      description: Please check if an issue already exists for the bug you encountered.
+      options:
+      - label: I have checked the troubleshooting document at https://github.com/OpenDevin/OpenDevin/blob/main/docs/guides/Troubleshooting.md
+        required: true
+      - label: I have checked the existing issues.
+        required: true
+
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Describe the bug
+      description: Provide a short description of the problem.
+    validations:
+      required: true
+
+  - type: textarea
+    id: current-version
+    attributes:
+      label: Current Version
+      description: What version are you using? If you're running in docker, tell us the tag you're using (e.g. ghcr.io/opendevin/opendevin:0.3.1).
+      render: bash
+    validations:
+      required: true
+
+  - type: textarea
+    id: config
+    attributes:
+      label: Installation and Configuration
+      description: Please provide any commands you ran and any configuration (redacting API keys)
+      render: bash
+    validations:
+      required: true
+
+  - type: textarea
+    id: model-agent
+    attributes:
+      label: Model and Agent
+      description: What model and agent are you using? You can see these settings in the UI by clicking the settings wheel.
+      placeholder: |
+        - Model:
+        - Agent:
+
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: Reproduction Steps
+      description: Please list the steps to reproduce the issue.
+      placeholder: |
+        1.
+        2.
+        3.
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Logs, Errors, Screenshots, and Additional Context
+      description: Please add any additional context about the problem here.
diff --git a/README.md b/README.md
@@ -144,7 +144,7 @@ If you want to use the (unstable!) bleeding edge, you can use `ghcr.io/opendevin
 
 See [Development.md](Development.md) for instructions on running OpenDevin without Docker.
 
-If you're running on Windows and having trouble, check out our [guide for Windows users](./docs/guides/Windows.md)
+Having trouble? Check out our [Troubleshooting Guide](./docs/guides/Troubleshooting.md).
 
 ## 🤖 LLM Backends
 OpenDevin can work with any LLM backend.

diff --git a/docs/guides/Troubleshooting.md b/docs/guides/Troubleshooting.md
@@ -0,0 +1,73 @@
+# Troubleshooting
+
+> If you're running on Windows and having trouble, check out our [guide for Windows users](./Windows.md)
+
+There are some error messages that get reported over and over by users.
+We'll try and make the install process easier, and to make these error messages
+better in the future. But for now, you can look for your error message below,
+and see if there are any workaround.
+
+For each of these error messages **there is an existing issue**. Please do not
+open an new issue--just comment there.
+
+If you find more information or a workaround for one of these issues, please
+open a PR to add details to this file.
+
+## Unable to connect to docker
+https://github.com/OpenDevin/OpenDevin/issues/1226
+
+### Symptoms
+```
+Error creating controller. Please check Docker is running using docker ps
+```
+```
+docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
+```
+
+### Details
+OpenDevin 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)
+
+
+## Unable to connect to SSH box
+https://github.com/OpenDevin/OpenDevin/issues/1156
+
+### Symptoms
+```
+self.shell = DockerSSHBox(
+...
+pexpect.pxssh.ExceptionPxssh: Could not establish connection to host
+```
+
+### Details
+By default, OpenDevin connects to a running container using SSH. On some machines,
+especially Windows, this seems to fail.
+
+### Workarounds
+* Restart your computer (sometimes works?)
+* Be sure to have the latest versions of WSL and Docker
+* Try [this reinstallation guide](https://github.com/OpenDevin/OpenDevin/issues/1156#issuecomment-2064549427)
+* Set `-e SANDBOX_TYPE=exec` to switch to the ExecBox docker container
+
+## Unable to connect to LLM
+https://github.com/OpenDevin/OpenDevin/issues/1208
+
+### Symptoms
+```
+  File "/app/.venv/lib/python3.12/site-packages/openai/_exceptions.py", line 81, in __init__
+    super().__init__(message, response.request, body=body)
+                              ^^^^^^^^^^^^^^^^
+AttributeError: 'NoneType' object has no attribute 'request'
+```
+
+### Details
+This usually happens with local LLM setups, when OpenDevin can't connect to the LLM server.
+See our guide for [local LLMs](./LocalLLMs.md) for more information.
+
+### Workarounds
+* Check your `LLM_BASE_URL`
+* Check that ollama is running OK
+* Make sure you're using `--add-host host.docker.internal=host-gateway` when running in docker