NousResearch/hermes-agent · error · RuntimeError

Voice mode requires an STT provider for transcription. Optio

Error message

Voice mode requires an STT provider for transcription.
Option 1: uv pip install faster-whisper  (free, local; `pip install faster-whisper` also works if pip is on PATH)
Option 2: Set GROQ_API_KEY (free tier)
Option 3: Set VOICE_TOOLS_OPENAI_KEY (paid)

What it means

Raised when microphone audio works but no speech-to-text backend is configured. Voice mode needs one of: local faster-whisper, GROQ_API_KEY (free-tier hosted Whisper), or VOICE_TOOLS_OPENAI_KEY (paid OpenAI). check_voice_requirements() reports stt_available/stt_key_set false for all three.

Source

Thrown at cli.py:12905

            if _is_termux_environment():
                details = reqs.get("details", "")
                if "Termux:API Android app is not installed" in details:
                    raise RuntimeError(
                        "Termux:API command package detected, but the Android app is missing.\n"
                        "Install/update the Termux:API Android app, then retry /voice on.\n"
                        "Fallback: pkg install python-numpy portaudio && python -m pip install sounddevice"
                    )
                raise RuntimeError(
                    "Voice mode requires either Termux:API microphone access or Python audio libraries.\n"
                    "Option 1: pkg install termux-api and install the Termux:API Android app\n"
                    "Option 2: pkg install python-numpy portaudio && python -m pip install sounddevice"
                )
            raise RuntimeError(
                "Voice mode requires sounddevice and numpy.\n"
                f"Install with: {sys.executable} -m pip install sounddevice numpy"
            )
        if not reqs.get("stt_available", reqs.get("stt_key_set")):
            raise RuntimeError(
                "Voice mode requires an STT provider for transcription.\n"
                "Option 1: uv pip install faster-whisper  "
                "(free, local; `pip install faster-whisper` also works if pip is on PATH)\n"
                "Option 2: Set GROQ_API_KEY (free tier)\n"
                "Option 3: Set VOICE_TOOLS_OPENAI_KEY (paid)"
            )

        # Prevent double-start from concurrent threads (atomic check-and-set)
        with self._voice_lock:
            if self._voice_recording:
                return
            self._voice_recording = True

        # Load silence detection params from config. Shape-safe: a
        # hand-edited ``voice: true`` / ``voice: cmd+b`` leaves
        # ``load_config()['voice']`` as a non-dict; coerce to {} so
        # continuous recording falls back to the documented defaults
        # instead of crashing on ``.get()``.

View on GitHub (pinned to c896c09c42)

Solutions

1. Free local: `uv pip install faster-whisper` (or plain pip) into the Hermes environment
2. Free hosted: set GROQ_API_KEY in ~/.hermes/.env
3. Paid: set VOICE_TOOLS_OPENAI_KEY in ~/.hermes/.env
4. Restart the CLI after adding a key so .env is re-read, then `/voice on`

Example fix

# before
/voice on  # RuntimeError: Voice mode requires an STT provider for transcription.

# after (pick one)
uv pip install faster-whisper
echo 'GROQ_API_KEY=...' >> ~/.hermes/.env
/voice on

import importlib.util, os
from tools.voice_mode import check_voice_requirements

def stt_ready() -> bool:
    reqs = check_voice_requirements()
    return bool(reqs.get("stt_available", reqs.get("stt_key_set")))

def any_stt_path() -> bool:
    return importlib.util.find_spec("faster_whisper") is not None or \
           bool(os.getenv("GROQ_API_KEY")) or bool(os.getenv("VOICE_TOOLS_OPENAI_KEY"))

try:
    cli._voice_start_recording()
except RuntimeError as e:
    if "STT provider" in str(e):
        show_setup_guide("voice-stt")  # faster-whisper / GROQ_API_KEY / VOICE_TOOLS_OPENAI_KEY
    else:
        raise

When it happens

Trigger: Running `/voice on` after fixing audio, on a machine with none of faster-whisper installed, GROQ_API_KEY set, or VOICE_TOOLS_OPENAI_KEY set in ~/.hermes/.env.

Common situations: Fresh installs where STT was never configured; the key was added to the shell env of a different session than the one running Hermes; faster-whisper installed into the wrong venv.

Related errors

• SSH remote mode is selected but no host is configured.
• Could not create directory: ${error.message}
• Provider '{_explicit}' is set in config.yaml but no API key
• No LLM provider configured for task={task} provider={resolve
• Provider '{_explicit}' is set in config.yaml but no API key

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