gortium/infra
1
1
Fork 0
Code Issues 13 Pull Requests 21 Actions Packages Projects 1 Releases Wiki Activity

Matrix Bridge ModuleNotFoundError - Dependency Installation Fix #4

New Issue
Open
opened 2026-04-29 03:02:43 +00:00 by Hermes · 0 comments
Hermes commented 2026-04-29 03:02:43 +00:00
Collaborator
Copy Link

Summary

Users connecting to Hermes via Matrix bridge encountered a ModuleNotFoundError: No module named 'openai' error, preventing all Matrix communications with the agent.

Status: ✅ Fixed (PR #3 pending merge)
Affected Service: Hermes Matrix Bridge
Severity: High (complete service outage for Matrix users)

Error Message

Sorry, I encountered an error (ModuleNotFoundError). No module named 'openai'
Try again or use /reset to start a fresh session.

Root Cause Analysis

The Hermes gateway uses an isolated virtual environment at /opt/hermes/.venv for dependency management. The compose configuration had two critical issues:

Issue 1: Wrong Installation Target

The entrypoint command installed packages to system Python:

command: "sh -c 'pip install openai matrix-nio[encryption] -q && hermes gateway run'"

But the gateway runs from the isolated venv:

/opt/hermes/.venv/bin/hermes gateway run

System Python packages are not accessible from the isolated venv.

Issue 2: Ephemeral Virtual Environment

Even if packages were installed to the venv correctly, the venv directory was not mounted to persistent storage. Container restarts would wipe all installed dependencies, causing the error to reappear.

Solution Implemented

Changes Made

File: /opt/data/infra/assets/compose/ai/compose.yml

1. Corrected installation target:

# Before
command: "sh -c 'pip install openai matrix-nio[encryption] -q && hermes gateway run'"

# After
command: "sh -c '/opt/hermes/.venv/bin/uv pip install openai matrix-nio[encryption] --system -q && /opt/hermes/.venv/bin/hermes gateway run'"

2. Added persistent venv storage:

volumes:
  - /mnt/HoardingCow_docker_data/Hermes/venv:/opt/hermes/.venv  # NEW

Technical Decisions

Decision Rationale
uv over pip Hermes uses astral-sh's uv (modern, faster package manager)
--system flag Required for installing into active venv from scripts
matrix-nio[encryption] Correct SDK for Hermes (asyncio-based, not mautrix); enables E2EE via Olm protocol
Persistent mount Survives container restarts and NixOS rebuilds

Related Pull Requests

  • Infra PR: #3 (updates compose submodule)
  • Compose PR: gortium/compose#2 (actual fix in compose.yml)

Deployment Instructions

After PR merge, deploy with:

cd /opt/data/infra
sudo nixos-rebuild switch --flake .#lazyworkhorse

The reloadTriggers mechanism in docker_manager.nix will detect the compose.yml hash change and recreate the container automatically.

Verification Steps

# 1. Check packages are installed
docker exec hermes /opt/hermes/.venv/bin/python -c "import openai, nio; print('OK')"
# Expected: OK

# 2. Test Matrix connectivity
# Send a message to Hermes via Matrix - should no longer receive ModuleNotFoundError

Prevention Measures

For Future PRs

  1. Always verify compose.yml variables - Check that all ${VAR} references are intact after edits
  2. Test in staging first - Deploy to non-critical host before production
  3. Use docker exec verification - Confirm imports work before testing end-to-end
  4. Document dependency changes - Any new Python packages need venv installation in entrypoint

Skill Updates

Updated gitea-create-pull-request skill with:

  • PR quality standards (clear problem statement, root cause, solution, rationale)
  • How to update existing PRs via PATCH API
  • SSL/port clarification (API uses 443, SSH uses 2222)

Timeline

  • Discovered: 2026-04-29
  • Root cause identified: 2026-04-29
  • Fix implemented: 2026-04-29
  • PRs created: 2026-04-29
  • PRs updated with quality descriptions: 2026-04-29
  • Expected merge: Pending review

References

  • Hermes Agent Skill: /opt/data/skills/autonomous-ai-agents/hermes-agent/SKILL.md
  • Matrix Bridge Fix Skill: /opt/data/skills/devops/hermes-matrix-bridge-fix/SKILL.md
  • Docker Manager Module: /opt/data/infra/modules/nixos/services/docker_manager.nix
## Summary Users connecting to Hermes via Matrix bridge encountered a `ModuleNotFoundError: No module named 'openai'` error, preventing all Matrix communications with the agent. **Status:** ✅ Fixed (PR #3 pending merge) **Affected Service:** Hermes Matrix Bridge **Severity:** High (complete service outage for Matrix users) --- ## Error Message ``` Sorry, I encountered an error (ModuleNotFoundError). No module named 'openai' Try again or use /reset to start a fresh session. ``` --- ## Root Cause Analysis The Hermes gateway uses an **isolated virtual environment** at `/opt/hermes/.venv` for dependency management. The compose configuration had two critical issues: ### Issue 1: Wrong Installation Target The entrypoint command installed packages to system Python: ```yaml command: "sh -c 'pip install openai matrix-nio[encryption] -q && hermes gateway run'" ``` But the gateway runs from the isolated venv: ```bash /opt/hermes/.venv/bin/hermes gateway run ``` System Python packages are not accessible from the isolated venv. ### Issue 2: Ephemeral Virtual Environment Even if packages were installed to the venv correctly, the venv directory was not mounted to persistent storage. Container restarts would wipe all installed dependencies, causing the error to reappear. --- ## Solution Implemented ### Changes Made **File:** `/opt/data/infra/assets/compose/ai/compose.yml` **1. Corrected installation target:** ```yaml # Before command: "sh -c 'pip install openai matrix-nio[encryption] -q && hermes gateway run'" # After command: "sh -c '/opt/hermes/.venv/bin/uv pip install openai matrix-nio[encryption] --system -q && /opt/hermes/.venv/bin/hermes gateway run'" ``` **2. Added persistent venv storage:** ```yaml volumes: - /mnt/HoardingCow_docker_data/Hermes/venv:/opt/hermes/.venv # NEW ``` ### Technical Decisions | Decision | Rationale | |----------|-----------| | `uv` over `pip` | Hermes uses astral-sh's `uv` (modern, faster package manager) | | `--system` flag | Required for installing into active venv from scripts | | `matrix-nio[encryption]` | Correct SDK for Hermes (asyncio-based, not mautrix); enables E2EE via Olm protocol | | Persistent mount | Survives container restarts and NixOS rebuilds | --- ## Related Pull Requests - **Infra PR:** https://code.lazyworkhorse.net/gortium/infra/pulls/3 (updates compose submodule) - **Compose PR:** https://code.lazyworkhorse.net/gortium/compose/pulls/2 (actual fix in compose.yml) --- ## Deployment Instructions After PR merge, deploy with: ```bash cd /opt/data/infra sudo nixos-rebuild switch --flake .#lazyworkhorse ``` The `reloadTriggers` mechanism in `docker_manager.nix` will detect the compose.yml hash change and recreate the container automatically. --- ## Verification Steps ```bash # 1. Check packages are installed docker exec hermes /opt/hermes/.venv/bin/python -c "import openai, nio; print('OK')" # Expected: OK # 2. Test Matrix connectivity # Send a message to Hermes via Matrix - should no longer receive ModuleNotFoundError ``` --- ## Prevention Measures ### For Future PRs 1. **Always verify compose.yml variables** - Check that all `${VAR}` references are intact after edits 2. **Test in staging first** - Deploy to non-critical host before production 3. **Use `docker exec` verification** - Confirm imports work before testing end-to-end 4. **Document dependency changes** - Any new Python packages need venv installation in entrypoint ### Skill Updates Updated `gitea-create-pull-request` skill with: - PR quality standards (clear problem statement, root cause, solution, rationale) - How to update existing PRs via PATCH API - SSL/port clarification (API uses 443, SSH uses 2222) --- ## Timeline - **Discovered:** 2026-04-29 - **Root cause identified:** 2026-04-29 - **Fix implemented:** 2026-04-29 - **PRs created:** 2026-04-29 - **PRs updated with quality descriptions:** 2026-04-29 - **Expected merge:** Pending review --- ## References - Hermes Agent Skill: `/opt/data/skills/autonomous-ai-agents/hermes-agent/SKILL.md` - Matrix Bridge Fix Skill: `/opt/data/skills/devops/hermes-matrix-bridge-fix/SKILL.md` - Docker Manager Module: `/opt/data/infra/modules/nixos/services/docker_manager.nix`
gortium self-assigned this 2026-04-29 23:43:49 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Hermes gortium
No Assignees gortium
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: gortium/infra#4
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?