Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix [Bug]: [Bug] Windows 11: Terminal execution fails (exit 126), File Access broken, and Doctor crash on GBK locale [4 pull requests, 3 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#18637•Fetched 2026-05-03 04:55:18
View on GitHub
Comments
3
Participants
3
Timeline
15
Reactions
0
Author
wzgrxwzgrx
Participants
alt-glitchalt-glitchteknium1teknium1wzgrxwzgrx
Timeline (top)
labeled ×5cross-referenced ×4commented ×3referenced ×2

Error Message

Observation: This happens on a fresh install where Git Bash/WSL might not be the primary shell. Hermes seems to rely on bash being available in the path but doesn't fallback to PowerShell/CMD or give a clear error. Example: Trying to read a valid file at E:\AI\hermes\config.yaml results in a "File not found" error, even though the file exists and is readable by the system. Error Log:

Fix Action

Fixed

PR fix notes

PR #17246: fix: resolve 7 identified issues [automated]

Description (problem / solution / changelog)

Summary

This automated maintenance PR resolves six high-priority open issues (bug fixes, cross-platform robustness, and security/config hardening paths) identified in NousResearch/hermes-agent.

Note: The job target was 7 issues. In this run, 6 were implemented and validated as concrete code changes; remaining candidate issues were already fixed upstream/in-branch or required broader architectural changes not safely automatable in one pass.

Issues resolved

  1. #18757 - resolve_api_key_provider_credentials() misses ~/.hermes/.env for base_url_env_var

    • Replaced os.getenv(...) with get_env_value(...) in API-key provider credential resolution.
    • Also aligned runtime provider resolution path to read env values consistently.

  2. #18705 - load_hermes_dotenv() overrides runtime env vars (override=True)

    • Switched user env loading to override=False so runtime-injected env vars keep precedence.
    • Updated function docstring behavior notes accordingly.

  3. #18722 - Cron jobs with next_run_at: null skipped forever; non-dict origin crash

    • Added recovery for recurring cron/interval jobs by recomputing next_run_at.
    • Hardened _resolve_origin() to tolerate non-dict origin payloads.

  4. #18742 - Kimi/Moonshot via aggregators misses reasoning-mode detection

    • _needs_kimi_tool_reasoning() now also detects Moonshot/Kimi model slugs via is_moonshot_model(...).

  5. #18744 - constraints_path dead config (not loaded)

    • Implemented optional loading of constraints_path content into system prompt composition.

  6. #18778 - Gateway scoped lock stale detection no-op on macOS/Windows

    • Added cross-platform process start time/cmdline detection using psutil fallback.
    • Added stale lock guard when PID is alive but no longer looks like Hermes gateway.

Files modified

  • hermes_cli/auth.py
  • hermes_cli/runtime_provider.py
  • hermes_cli/env_loader.py
  • cron/jobs.py
  • cron/scheduler.py
  • run_agent.py
  • gateway/status.py

Commit list

  • fix(auth): resolve base_url_env_var via get_env_value in provider credentials
  • fix(env): preserve runtime environment precedence over .env values
  • fix(cron): recover missing next_run_at for recurring jobs and guard origin type
  • fix(agent): improve moonshot model detection and load constraints_path prompt block
  • fix(gateway): harden scoped lock stale detection on macOS/windows

Changed files

  • Dockerfile (modified, +3/-2)
  • acp_adapter/session.py (modified, +12/-0)
  • agent/auxiliary_client.py (modified, +280/-28)
  • agent/context_compressor.py (modified, +496/-52)
  • agent/title_generator.py (modified, +2/-2)
  • agent/transports/chat_completions.py (modified, +14/-0)
  • agent/usage_pricing.py (modified, +4/-0)
  • cli-config.yaml.example (modified, +5/-0)
  • cli.py (modified, +27/-3)
  • cron/jobs.py (modified, +10/-2)
  • cron/scheduler.py (modified, +14/-4)
  • docker/entrypoint.sh (modified, +9/-1)
  • gateway/channel_directory.py (modified, +14/-4)
  • gateway/platforms/discord.py (modified, +33/-7)
  • gateway/platforms/email.py (modified, +12/-2)
  • gateway/platforms/feishu.py (modified, +34/-1)
  • gateway/platforms/qqbot/adapter.py (modified, +8/-2)
  • gateway/platforms/telegram_network.py (modified, +7/-2)
  • gateway/platforms/weixin.py (modified, +10/-1)
  • gateway/run.py (modified, +129/-32)
  • gateway/status.py (modified, +37/-2)
  • hermes_cli/auth.py (modified, +4/-4)
  • hermes_cli/commands.py (modified, +1/-1)
  • hermes_cli/config.py (modified, +271/-40)
  • hermes_cli/copilot_auth.py (modified, +1/-1)
  • hermes_cli/doctor.py (modified, +6/-1)
  • hermes_cli/env_loader.py (modified, +5/-4)
  • hermes_cli/gateway.py (modified, +16/-13)
  • hermes_cli/main.py (modified, +69/-3)
  • hermes_cli/memory_setup.py (modified, +1/-1)
  • hermes_cli/model_switch.py (modified, +6/-1)
  • hermes_cli/models.py (modified, +60/-2)
  • hermes_cli/profiles.py (modified, +16/-3)
  • hermes_cli/runtime_provider.py (modified, +17/-14)
  • hermes_cli/setup.py (modified, +8/-2)
  • hermes_cli/slack_cli.py (modified, +1/-2)
  • hermes_cli/status.py (modified, +17/-2)
  • hermes_cli/web_server.py (modified, +1/-1)
  • hermes_constants.py (modified, +16/-3)
  • model_tools.py (modified, +44/-13)
  • run_agent.py (modified, +413/-82)
  • setup-hermes.sh (modified, +23/-12)
  • skills/red-teaming/godmode/scripts/load_godmode.py (modified, +9/-8)
  • tests/agent/test_context_compressor.py (modified, +389/-0)
  • tests/agent/transports/test_chat_completions.py (modified, +11/-0)
  • tests/gateway/test_compress_command.py (modified, +49/-0)
  • tests/hermes_cli/test_api_key_providers.py (modified, +5/-5)
  • tests/hermes_cli/test_config.py (modified, +17/-0)
  • tests/run_agent/test_413_compression.py (modified, +81/-1)
  • tests/run_agent/test_compression_boundary_hook.py (modified, +42/-0)
  • tests/run_agent/test_run_agent.py (modified, +100/-13)
  • tests/tools/test_skill_manager_tool.py (modified, +270/-0)
  • tools/approval.py (modified, +1/-1)
  • tools/delegate_tool.py (modified, +4/-1)
  • tools/environments/docker.py (modified, +36/-5)
  • tools/environments/local.py (modified, +8/-1)
  • tools/file_operations.py (modified, +70/-67)
  • tools/file_tools.py (modified, +13/-2)
  • tools/send_message_tool.py (modified, +72/-2)
  • tools/session_search_tool.py (modified, +2/-2)
  • tools/skill_manager_tool.py (modified, +82/-21)
  • tools/skills_tool.py (modified, +13/-1)
  • tools/terminal_tool.py (modified, +6/-0)
  • tools/tool_backend_helpers.py (modified, +15/-5)
  • tools/tts_tool.py (modified, +27/-16)
  • tools/voice_mode.py (modified, +23/-10)
  • toolsets.py (modified, +14/-1)
  • tui_gateway/server.py (modified, +5/-3)
  • ui-tui/src/app/turnController.ts (modified, +1/-1)
  • ui-tui/src/app/useInputHandlers.ts (modified, +8/-3)
  • ui-tui/src/app/useSessionLifecycle.ts (modified, +1/-1)
  • ui-tui/src/gatewayTypes.ts (modified, +1/-0)
  • utils.py (modified, +9/-0)
  • uv.lock (modified, +161/-2)
  • website/docs/reference/environment-variables.md (modified, +1/-1)

PR #18721: fix(cli): decode .env as UTF-8 to avoid GBK crash on Windows

Description (problem / solution / changelog)

Path.read_text() uses the system locale by default. On Windows CN/JP/KR locales (GBK/CP932/CP949), reading a UTF-8 .env raises UnicodeDecodeError as soon as it contains any non-ASCII byte (e.g. an em dash).

Pin encoding="utf-8" on every .env read in hermes_cli to match how the rest of the codebase (load_dotenv at doctor.py:26) already decodes it.

Adds a regression test that monkeypatches Path.read_text to simulate a GBK locale and asserts 'hermes doctor' no longer raises.

Refs #18637

What does this PR do?

<!-- Describe the change clearly. What problem does it solve? Why is this approach the right one? -->

Related Issue

<!-- Link the issue this PR addresses. If no issue exists, consider creating one first. -->

Fixes #

Type of Change

<!-- Check the one that applies. -->
  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests (adding or improving test coverage)
  • ♻️ Refactor (no behavior change)
  • 🎯 New skill (bundled or hub)

Changes Made

<!-- List the specific changes. Include file paths for code changes. -->

How to Test

<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->

Checklist

<!-- Complete these before requesting review. -->

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
  • I searched for existing PRs to make sure this isn't a duplicate
  • My PR contains only changes related to this fix/feature (no unrelated commits)
  • I've run pytest tests/ -q and all tests pass
  • I've added tests for my changes (required for bug fixes, strongly encouraged for features)
  • I've tested on my platform: <!-- e.g. Ubuntu 24.04, macOS 15.2, Windows 11 -->

Documentation & Housekeeping

<!-- Check all that apply. It's OK to check "N/A" if a category doesn't apply to your change. -->
  • I've updated relevant documentation (README, docs/, docstrings) — or N/A
  • I've updated cli-config.yaml.example if I added/changed config keys — or N/A
  • I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
  • I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
  • I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

<!-- Only fill this out if you're adding a skill. Delete this section otherwise. -->
  • This skill is broadly useful to most users (if bundled) — see Contributing Guide
  • SKILL.md follows the standard format (frontmatter, trigger conditions, steps, pitfalls)
  • No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
  • I've tested the skill end-to-end: hermes --toolsets skills -q "Use the X skill to do Y"

Screenshots / Logs

<!-- If applicable, add screenshots or log output showing the fix/feature in action. -->

Changed files

  • hermes_cli/doctor.py (modified, +5/-2)
  • hermes_cli/main.py (modified, +1/-1)
  • hermes_cli/memory_setup.py (modified, +1/-1)
  • tests/hermes_cli/test_doctor.py (modified, +51/-0)

PR #18743: fix(cli): decode .env as UTF-8 to avoid GBK crash (salvage #18721)

Description (problem / solution / changelog)

Pins encoding="utf-8" on all three .env read_text() call sites in hermes_cli, matching how the rest of the codebase already decodes .env via load_dotenv. Drive-by fix for issue #18637 bug 3 (Windows GBK locale crash); the other two reports in that issue are Windows-native terminal/path issues that are out of scope.

Cherry-picked from @CoreyNoDream's PR #18721 onto current main.

Changes

  • hermes_cli/doctor.py: pin UTF-8 on the .env read at run_doctor()
  • hermes_cli/main.py: pin UTF-8 in _has_any_provider_configured()
  • hermes_cli/memory_setup.py: pin UTF-8 in _write_env_vars()
  • tests/hermes_cli/test_doctor.py: regression test simulating GBK locale
  • scripts/release.py: AUTHOR_MAP entry for CoreyNoDream

Validation

  • E2E: simulated GBK locale with monkeypatched Path.read_text. Pre-fix path raises UnicodeDecodeError; post-fix path succeeds and _has_any_provider_configured() returns True as expected.
  • scripts/run_tests.sh tests/hermes_cli/test_doctor.py → 29 passed.

Changed files

  • hermes_cli/doctor.py (modified, +5/-2)
  • hermes_cli/main.py (modified, +1/-1)
  • hermes_cli/memory_setup.py (modified, +1/-1)
  • scripts/release.py (modified, +1/-0)
  • tests/hermes_cli/test_doctor.py (modified, +51/-0)

PR #18782: fix: decode config and state files as UTF-8 on non-UTF-8 locales

Description (problem / solution / changelog)

Several file-I/O call sites still use open() / Path.read_text() / Path.write_text() without an explicit encoding, so they fall back to the platform default. On Windows CN/JP/KR locales (GBK/CP932/CP949) any non-ASCII byte in a config/state/user-content file raises UnicodeDecodeError or UnicodeEncodeError and crashes the caller.

#18721 fixed this for the .env read path; this extends the same fix to the remaining hot paths:

  • agent/copilot_acp_client.py: fs/read_text_file and fs/write_text_file (Copilot's read_file / write_file tools, directly reported in #18637 bug 2)
  • agent/model_metadata.py: context-length YAML cache load + two save sites (context probing is on the call path of every model invocation)
  • agent/nous_rate_guard.py: cross-session rate-limit JSON state (read + atomic write via os.fdopen)
  • cron/scheduler.py: user config.yaml read in run_job
  • gateway/delivery.py: cron output writes for AI-generated content, very likely non-ASCII

yaml.dump call sites also gain allow_unicode=True so the emitted YAML preserves non-ASCII chars as-is instead of emitting \u escape sequences.

Adds regression tests that monkeypatch builtins.open / Path.read_text / Path.write_text to simulate a GBK locale: each test raises UnicodeDecodeError / UnicodeEncodeError unless the caller explicitly passes encoding='utf-8'. Verified that the tests fail on main and pass with this change, on Linux as well as on Windows.

Refs #18637

What does this PR do?

<!-- Describe the change clearly. What problem does it solve? Why is this approach the right one? -->

Related Issue

<!-- Link the issue this PR addresses. If no issue exists, consider creating one first. -->

Fixes #

Type of Change

<!-- Check the one that applies. -->
  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests (adding or improving test coverage)
  • ♻️ Refactor (no behavior change)
  • 🎯 New skill (bundled or hub)

Changes Made

<!-- List the specific changes. Include file paths for code changes. -->

How to Test

<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->

Checklist

<!-- Complete these before requesting review. -->

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
  • I searched for existing PRs to make sure this isn't a duplicate
  • My PR contains only changes related to this fix/feature (no unrelated commits)
  • I've run pytest tests/ -q and all tests pass
  • I've added tests for my changes (required for bug fixes, strongly encouraged for features)
  • I've tested on my platform: <!-- e.g. Ubuntu 24.04, macOS 15.2, Windows 11 -->

Documentation & Housekeeping

<!-- Check all that apply. It's OK to check "N/A" if a category doesn't apply to your change. -->
  • I've updated relevant documentation (README, docs/, docstrings) — or N/A
  • I've updated cli-config.yaml.example if I added/changed config keys — or N/A
  • I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
  • I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
  • I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

<!-- Only fill this out if you're adding a skill. Delete this section otherwise. -->
  • This skill is broadly useful to most users (if bundled) — see Contributing Guide
  • SKILL.md follows the standard format (frontmatter, trigger conditions, steps, pitfalls)
  • No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
  • I've tested the skill end-to-end: hermes --toolsets skills -q "Use the X skill to do Y"

Screenshots / Logs

<!-- If applicable, add screenshots or log output showing the fix/feature in action. -->

Changed files

  • agent/copilot_acp_client.py (modified, +2/-2)
  • agent/model_metadata.py (modified, +5/-5)
  • agent/nous_rate_guard.py (modified, +2/-2)
  • cron/scheduler.py (modified, +1/-1)
  • gateway/delivery.py (modified, +2/-2)
  • tests/agent/test_copilot_acp_client.py (modified, +78/-0)
  • tests/agent/test_model_metadata.py (modified, +62/-0)
  • tests/agent/test_nous_rate_guard.py (modified, +45/-0)
RAW_BUFFERClick to expand / collapse

I installed Hermes Agent using the official script on a clean Windows 11 system. I am encountering three critical bugs that make the agent unusable out-of-the-box:

1. Terminal Execution Fails (Exit Code 126)                                                                                           
Issue: The terminal toolset is enabled and configured as local, but NO commands can be executed. Every command (even simple ones like echo hello or pwd) fails with exit_code 126.                                                                                              
Observation: This happens on a fresh install where Git Bash/WSL might not be the primary shell. Hermes seems to rely on bash being available in the path but doesn't fallback to PowerShell/CMD or give a clear error.                                                          
                                                                                                                                      
2. File Access Tools Cannot Read Files                                                                                                
Issue: The read_file tool fails to read existing files.                                                                               
Example: Trying to read a valid file at E:\AI\hermes\config.yaml results in a "File not found" error, even though the file exists and is readable by the system.                                                                                                                
Impact: The agent is effectively blind and cannot inspect the codebase or configuration.                                              
                                                                                                                                      
3. hermes doctor Crash on Windows Chinese Locale                                                                                      
Issue: Running hermes doctor crashes immediately when trying to read the .env file.                                                   
Error Log:                                                                                                                            
text                                                                                                                                  
UnicodeDecodeError: 'gbk' codec can't decode byte 0x94 in position 661: illegal multibyte sequence                                    
  File "...\hermes_cli\doctor.py", line 267, in run_doctor                                                                            
    content = env_path.read_text()                                                                                                    
                                                                                                                                      
Cause: Python on Windows uses the system locale (GBK for Chinese Windows) by default. Since .env files are UTF-8, read_text() fails.  
                                                                                                                                      
Environment                                                                                                                           
- OS: Windows 11 (Chinese Edition, GBK default encoding)                                                                              
- Python: 3.11.15                                                                                                                     
- Hermes Version: [Insert Version here]                                                                                               
- Shell: PowerShell / CMD                                                                                                             
                                                                                                                                      
Expected Behavior                                                                                                                     
1. Terminal should work on Windows (fallback to cmd.exe or powershell.exe if bash is missing).                                        
2. File tools should handle Windows paths (backslashes) correctly.                                                                    
3. hermes doctor should explicitly open files as UTF-8.

extent analysis

TL;DR

The most likely fix involves modifying the Hermes Agent to handle Windows-specific paths and encoding, and ensuring it can fallback to PowerShell or CMD when bash is not available.

Guidance

  • Verify that the system's PATH environment variable includes the directory containing cmd.exe or powershell.exe to ensure the terminal toolset can fallback correctly.
  • Check the hermes_cli\doctor.py file to see if the read_text() function can be modified to explicitly open files with UTF-8 encoding, such as using env_path.read_text(encoding='utf-8').
  • Test the file access tools with forward slashes (/) instead of backslashes (\) to see if it resolves the "File not found" error.
  • Consider setting the system locale to a UTF-8 compatible encoding to avoid encoding issues with Python.

Example

# In hermes_cli\doctor.py, line 267
content = env_path.read_text(encoding='utf-8')

Notes

The provided solution assumes that the issue is related to the encoding and path handling in the Hermes Agent. However, without the exact version of Hermes, it's difficult to provide a more specific fix.

Recommendation

Apply workaround: Modify the hermes_cli\doctor.py file to explicitly open files with UTF-8 encoding, and test the file access tools with forward slashes to resolve the path handling issue. This should provide a temporary solution until a more permanent fix is available.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#cache error#pipeline error#runtime error#dependency conflict#file not found

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING