mirror of
https://github.com/nesquena/hermes-webui.git
synced 2026-05-25 11:10:18 +00:00
nesquena-hermes
29878259ca
Closes #1695. @Patrick-81 reported the bare "AIAgent not available -- check that hermes-agent is on sys.path" error on a symlinked install (~/Programmes/hermes-agent linked to ~/hermes-agent). The maintainer's response — three diagnostic commands plus `pip install -e .` in the agent dir — fixed it for them. This PR captures both halves of that learning so the next user with the same shape doesn't have to file a new issue: 1. **Error message diagnostic block.** New helper `_aiagent_import_error_detail()` in api/streaming.py builds a multi-line diagnostic when the import fails, including: - the running Python interpreter - HERMES_WEBUI_AGENT_DIR (set value, or "(not set)") - sys.path entries that mention hermes/agent (or "no entries mention..." — itself a strong diagnostic signal) - the most-common fix (`pip install -e .` in the agent dir) - a pointer to docs/troubleshooting.md The original error message string is preserved as the FIRST line so existing log scrapers and docs-search keep matching. Helper is kept as a separate function so it stays out of the hot path until we actually need to raise — building it on every successful import would be wasted work. 2. **New docs/troubleshooting.md.** Symptom → Why → Diagnostic commands → Fix → When-to-file-a-bug template, with one entry to start: the "AIAgent not available" flow Patrick-81 walked through. Future recurring failure modes follow the same template. Required a one-line addition to .gitignore — docs/* is gitignored with an allowlist, and the new file needed `!docs/troubleshooting.md` to be tracked. 3. **README link.** docs/troubleshooting.md added to the `## Docs` section so users know where to look first. 13 regression tests in tests/test_1695_aiagent_import_error_detail.py: 9 for the helper output shape (preserves original message line, includes running python, shows HERMES_WEBUI_AGENT_DIR set/unset both ways, includes pip-install-e hint, points at troubleshooting doc, lists relevant sys.path entries when present, says "no entries..." when absent, output is multi-line) plus 4 for the docs-presence regression (file exists, has the AIAgent section, includes pip install -e ., describes the diagnostic chain with readlink + agent/__init__.py verification). 190 streaming/aiagent tests pass after the change. ast.parse on api/streaming.py clean. CI failure on prior push was due to the docs/* gitignore swallowing the new troubleshooting.md file silently — this commit adds the allowlist entry so the file is tracked.
98 lines
4.9 KiB
Markdown
98 lines
4.9 KiB
Markdown
# Troubleshooting
|
|
|
|
Concrete diagnostic flows for the most common failure modes when running Hermes WebUI. Each entry has the symptom, the diagnostic commands you should run *before* opening an issue, and the fix that has worked for past reporters.
|
|
|
|
If your symptom isn't listed and the diagnostics don't narrow it down, file a bug at https://github.com/nesquena/hermes-webui/issues — include the **full output** of every command in the relevant section.
|
|
|
|
---
|
|
|
|
## "AIAgent not available -- check that hermes-agent is on sys.path"
|
|
|
|
**Symptom.** WebUI starts, shows the chat interface, but every chat request fails immediately with this error in the response or the server log. As of v0.51.6 the error includes a diagnostic block with the running Python interpreter, the relevant `sys.path` entries, and the most-common fix; on older versions the message is bare.
|
|
|
|
**Why it happens.** The WebUI imports the agent class at chat time via `from run_agent import AIAgent`. That import only succeeds if the running Python's `sys.path` contains either the hermes-agent checkout or a pip-installed copy of the agent. Three common failure modes:
|
|
|
|
1. **Agent installed but not on `sys.path`.** Most common. The agent is checked out somewhere (e.g. `~/Programmes/hermes-agent`), the WebUI was launched with a Python that doesn't know about it, and there's no `pip install -e .` linking the two.
|
|
2. **Symlink with a typo or wrong target.** A symlink to the agent looks correct on `ls`, but `readlink` resolves to a path that doesn't exist or doesn't contain `agent/__init__.py`.
|
|
3. **`HERMES_WEBUI_AGENT_DIR` set to the wrong directory.** Override env var beats auto-discovery and points at a directory that has no agent code.
|
|
|
|
### Step 1 — confirm the agent location
|
|
|
|
```bash
|
|
# If you have ~/hermes-agent (the default location):
|
|
ls -la ~/hermes-agent
|
|
readlink ~/hermes-agent # if it's a symlink, where does it resolve?
|
|
ls ~/hermes-agent/agent/__init__.py 2>&1
|
|
```
|
|
|
|
The third command must succeed (the file must exist). If it fails, your symlink is broken or pointing at a directory that's missing the agent module — fix that first.
|
|
|
|
### Step 2 — confirm the WebUI is using the right Python
|
|
|
|
```bash
|
|
cd ~/hermes-webui && ./start.sh 2>&1 | grep -iE 'agent|python|hermes_webui_python' | head -20
|
|
```
|
|
|
|
The startup banner prints which Python and agent dir it resolved. If the agent dir is empty or the Python is the wrong one, set the override:
|
|
|
|
```bash
|
|
export HERMES_WEBUI_AGENT_DIR=/absolute/path/to/hermes-agent
|
|
export HERMES_WEBUI_PYTHON=/absolute/path/to/agent/venv/bin/python
|
|
./start.sh
|
|
```
|
|
|
|
### Step 3 — install the agent in editable mode
|
|
|
|
This is the most common fix and resolves the original issue #1695:
|
|
|
|
```bash
|
|
cd /path/to/hermes-agent # the directory holding pyproject.toml + the agent/ module
|
|
pip install -e . # use the same python that runs the WebUI
|
|
```
|
|
|
|
Then restart the WebUI:
|
|
|
|
```bash
|
|
cd ~/hermes-webui
|
|
./start.sh
|
|
```
|
|
|
|
### Step 4 — verify by importing manually
|
|
|
|
If steps 1-3 still don't work, check whether the WebUI's Python can import the agent at all:
|
|
|
|
```bash
|
|
$HERMES_WEBUI_PYTHON -c "from run_agent import AIAgent; print('ok')" 2>&1
|
|
```
|
|
|
|
(Replace `$HERMES_WEBUI_PYTHON` with the actual Python path from step 2 if the env var isn't set.) If this prints `ok`, the agent IS on `sys.path` for that Python — and the WebUI should work.
|
|
|
|
If this fails, `import run_agent` itself is broken — check that the agent's pyproject.toml lists `run_agent` as a top-level module or that the agent dir is on PYTHONPATH:
|
|
|
|
```bash
|
|
PYTHONPATH=/path/to/hermes-agent $HERMES_WEBUI_PYTHON -c "from run_agent import AIAgent; print('ok')"
|
|
```
|
|
|
|
If adding PYTHONPATH fixes it, persist the path either via `pip install -e .` (preferred) or by setting `HERMES_WEBUI_AGENT_DIR` to that directory.
|
|
|
|
### When to file a bug
|
|
|
|
If after running steps 1-4 the import still fails *and* `pip install -e .` succeeded *and* `PYTHONPATH=... python -c "from run_agent import AIAgent"` succeeds — that's a real WebUI bug. File at https://github.com/nesquena/hermes-webui/issues with:
|
|
|
|
- The output of every command in steps 1-4
|
|
- The full diagnostic block printed by the WebUI's `ImportError` (v0.51.6+)
|
|
- Your OS, Python version, and how the agent was installed
|
|
|
|
---
|
|
|
|
## Other troubleshooting
|
|
|
|
This document grows over time. If a recurring failure mode isn't covered here yet, add it via PR. The format for each entry: **Symptom → Why → Diagnostic commands → Fix → When to file a bug**.
|
|
|
|
Related references:
|
|
|
|
- [`docs/supervisor.md`](supervisor.md) — process-supervisor setup (launchd, systemd, supervisord, runit/s6) including the bootstrap supervisor-foreground flag.
|
|
- [`docs/docker.md`](docker.md) — Docker compose setup, common failure modes, bind-mount migration.
|
|
- [`docs/wsl-autostart.md`](wsl-autostart.md) — WSL2 auto-start at login on Windows.
|
|
- [`docs/EXTENSIONS.md`](EXTENSIONS.md) — WebUI extension injection, security model, examples.
|