# NousResearch/hermes-agent · Doctor falsely flags valid config keys as unknown

## Open now

- Nothing open on GitHub.

A bug where \`hermes doctor\` incorrectly warns that supported top-level config keys like \`group_sessions_per_user\` and \`known_plugin_toolsets\` are unknown or ignored. Multiple fix attempts address adding these keys to an allowlist (\`_EXTRA_KNOWN_ROOT_KEYS\`) to suppress the false warnings.

## TL;DR

- 11 member(s): 0 open issue(s), 4 closed issue(s), 0 open PR(s), 1 merged PR(s), 6 PR(s) closed without merging.
- A fix was merged to main in PR #67891. Verify it addresses your case.
- **Recommended:** read PR #67891 (and any competing PRs below) before filing. Confirm the merged change covers your symptom.

## Maintainer resolution verdict

- Internal-tracker verdict over this cluster's issue members: `partially_resolved` · deciding PR(s): `pr-67891`. This is distinct from the fix status above. Weigh it yourself.

## How this cluster was grouped

- Link evidence (`STRUCTURAL_PARTIAL`): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
- Members outside that structural core may belong to a different underlying problem.
- Pairwise link density `0.17`: the share of member pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. `1.00` means every pair is linked.

## Closed / duplicate issues

- #67397: \[Bug\]: \`hermes doctor\` flags supported top-level config keys \`group_sessions_per_user\` and \`known_plugin_toolsets\` as unknown
- #67478: \[Bug\] follow-up #67397: _EXTRA_KNOWN_ROOT_KEYS still missing group_sessions_per_user + known_plugin_toolsets on main
- #67860: \[Bug\]: ⚠ Config issues detected in config.yaml:
- #68000: Doctor reports runtime-supported root config keys as ignored

## Prior & competing PRs

- **#67497: fix(config): add group_sessions_per_user + known_plugin_toolsets to _EXTRA_KNOWN_ROOT_KEYS (#67478)**. closed without merge · fix tier `suggested`
  - maintainer direction: category `uncategorized`; implication `needs_llm`; refs `#67924`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#67513: fix(config): add group_sessions_per_user and known_plugin_toolsets to _EXTRA_KNOWN_ROOT_KEYS**. closed without merge · fix tier `suggested`
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`
  - _suggested-tier fix detail withheld; re-request with `?tier=all` to include it._
- **#67891: fix(config): stop doctor flagging all Hermes-written top-level config keys**. merged to main · fix tier `verified`
  - maintainer direction: category `merged`; implication `superseded`
  - files: `hermes_cli/config.py`, `tests/hermes_cli/test_config_validation.py`
  - fix hunks:
  - `hermes_cli/config.py`

    ```diff
    @@ -5512,7 +5512,14 @@ def check_config_version() -> Tuple[int, int]:
         "plugins",           # plugin enable/disable lists (hermes_cli/plugins_cmd.py)
         "smart_model_routing",   # written by the setup wizard (hermes_cli/setup.py)
         "platform_toolsets",     # written by the setup wizard (hermes_cli/setup.py)
    +    "known_plugin_toolsets", # written/read by hermes_cli/tools_config.py toolset-save flow
         "session_reset",         # top-level form read by gateway/config.py + setup
    +    "group_sessions_per_user",   # top-level form bridged by gateway/config.py
    +    "thread_sessions_per_user",  # top-level form bridged by gateway/config.py
    +    "stt_echo_transcripts",      # top-level form bridged by gateway/config.py
    +    "reset_triggers",            # top-level form bridged by gateway/config.py
    +    "always_log_local",          # top-level form bridged by gateway/config.py
    +    "filter_silence_narration",  # top-level form bridged by gateway/config.py
         "multiplex_profiles",    # top-level form accepted alongside gateway.multiplex_profiles
         "profile_routes",        # top-level form accepted alongside gateway.profile_routes
         "platforms",             # top-level per-platform map merged by gateway/config.py
    ```
  - `tests/hermes_cli/test_config_validation.py`

    ```diff
    @@ -253,6 +253,28 @@ def test_known_root_keys_derived_from_default_config(self):
             assert _EXTRA_KNOWN_ROOT_KEYS.issubset(_KNOWN_ROOT_KEYS)
             assert _KNOWN_ROOT_KEYS == frozenset(DEFAULT_CONFIG.keys()) | _EXTRA_KNOWN_ROOT_KEYS
     
    +    def test_hermes_written_roots_not_flagged_as_unknown(self):
    +        """Roots Hermes itself writes/reads must not warn as unknown (#67397)."""
    +        issues = validate_config_structure({
    +            "model": {"provider": "openrouter"},
    +            "known_plugin_toolsets": {"cli": ["spotify"]},
    +            "group_sessions_per_user": True,
    +            "thread_sessions_per_user": False,
    +            "stt_echo_transcripts": True,
    +            "reset_triggers": ["/new"],
    +            "always_log_local": True,
    +            "filter_silence_narration": True,
    +        })
    +        unknown = [i for i in issues if "Unknown top-level config key" in i.message]
    +        messages = " ".join(i.message for i in unknown)
    +        assert "known_plugin_toolsets" not in messages
    +        assert "group_sessions_per_user" not in messages
    +        assert "thread_sessions_per_user" not in messages
    +        assert "stt_echo_transcripts" not in messages
    +        assert "reset_triggers" not in messages
    +        assert "always_log_local" not in messages
    +        assert "filter_silence_narration" not in messages
    +
         def test_provider_like_unknown_root_keeps_misplaced_message(self):
             """Preserve existing base_url/api_key root-level guidance (not generic unknown)."""
             issues = validate_config_structure({
    ```
- **#67517: fix(config): 添加 group_sessions_per_user 和 known_plugin_toolsets 到白名单**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#67497`, `#67447`
- **#67583: fix(cli): recognize group_sessions_per_user and known_plugin_toolsets as known config roots (#67478)**. closed without merge
  - maintainer direction: category `duplicate_of`; implication `duplicate`; refs `#67497`, `#67447`
- **#67654: fix(config,doctor): accept known roots and synthetic slugs**. closed without merge
  - maintainer direction: category `wontfix_bydesign`; implication `wontfix`; refs `#67924`
- **#68023: fix(config): add runtime-supported keys to _EXTRA_KNOWN_ROOT_KEYS (#68000)**. closed without merge
  - maintainer direction: category `implemented_elsewhere`; implication `superseded`; refs `9bda6438d41`, `#67924`, `#68000`

## Fix status

- Merged to main in PR #67891 (cited above). No release data is tracked. Verify downstream.
- Fix last verified (merged) `2026-07-20`.
- Subsystem: `hermes_cli`