NousResearch/hermes-agent · error · ValueError

path is a sensitive credential or internal Hermes path and c

Error message

path is a sensitive credential or internal Hermes path and cannot be attached

What it means

The attached file reference lives inside a sensitive directory (entries of _SENSITIVE_HOME_DIRS or _SENSITIVE_HERMES_DIRS under ~ or the HERMES_HOME). The second tier of _ensure_reference_path_allowed in agent/context_references.py uses Path.relative_to() against each blocked directory to reject anything nested within them, guarding internal Hermes state and credential stores from being inlined into context.

Source

Thrown at agent/context_references.py:502

def _ensure_reference_path_allowed(path: Path) -> None:
    from hermes_constants import get_hermes_home
    home = Path(os.path.expanduser("~")).resolve()
    hermes_home = get_hermes_home().resolve()

    blocked_exact = {home / rel for rel in _SENSITIVE_HOME_FILES}
    blocked_exact.add(hermes_home / ".env")
    blocked_dirs = [home / rel for rel in _SENSITIVE_HOME_DIRS]
    blocked_dirs.extend(hermes_home / rel for rel in _SENSITIVE_HERMES_DIRS)

    if path in blocked_exact:
        raise ValueError("path is a sensitive credential file and cannot be attached")

    for blocked_dir in blocked_dirs:
        try:
            path.relative_to(blocked_dir)
        except ValueError:
            continue
        raise ValueError("path is a sensitive credential or internal Hermes path and cannot be attached")

    # Anchor to the canonical read deny-list (agent/file_safety.get_read_block_error),
    # the single source of truth used by the file/terminal read path. The narrow
    # list above predates that guard and never caught the real credential stores:
    # provider keys (auth.json), Anthropic OAuth tokens (.anthropic_oauth.json),
    # MCP OAuth material (mcp-tokens/), webhook HMAC secrets, and project-local
    # .env files. That gap matters because the gateway feeds UNTRUSTED remote
    # message text into reference expansion, so `@file:~/.hermes/auth.json` from a
    # chat peer would otherwise read the operator's keys straight into context.
    # Routing through the canonical guard closes the gap today and keeps this path
    # protected automatically whenever that deny-list grows.
    try:
        from agent.file_safety import get_read_block_error

        if get_read_block_error(str(path)) is not None:
            raise ValueError(
                "path is a sensitive credential or internal Hermes path and cannot be attached"
            )

View on GitHub (pinned to c896c09c42)

Solutions

Attach a copy of the (redacted) data placed in the workspace instead of the live file under the sensitive directory.
Use built-in surface instead: hermes logs or slash commands to inspect Hermes state safely.
Never point @file: at anything under ~/.hermes/ credential/internal directories.

Example fix

# before
@file:~/.hermes/auth.json
# after — export names only, not values
hermes provider list   # then attach the non-secret output saved in the workspace

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
import os

def is_in_sensitive_dir(p: Path) -> bool:
    home = Path(os.path.expanduser('~')).resolve()
    for d in ('.hermes', '.ssh', '.gnupg'):  # mirror the sensitive dirs policy
        try:
            p.resolve().relative_to(home / d)
            return True
        except ValueError:
            continue
    return False

Try / catch

try:
    attach(path)
except ValueError as e:
    if "sensitive credential or internal Hermes path" in str(e):
        # copy redacted data into the workspace instead
        ...

Prevention

Do not point @file: references under ~/.hermes/ or other sensitive home dirs
Use hermes logs / slash commands to inspect agent state instead of attaching files
Copy only the needed non-secret data into the workspace before referencing

When it happens

Trigger: An @file: reference whose resolved path is under a blocked directory, e.g. @file:~/.hermes/auth.json, @file:~/.hermes/sessions/x.json, or any path within the sensitive home/HERMES_HOME directory lists. Matched by the relative_to loop over blocked_dirs.

Common situations: Asking the agent to inspect its own session or auth state for debugging; remote chat peers probing ~/.hermes/* stores through the gateway's reference expansion.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/f9cd927ed94180a2. Report an issue: GitHub.