Repository navigation
Troubleshooting
Common symptoms and what they mean. For each, there's a "what to check" list and a pointer to the wiki page that explains the underlying machinery in detail.
The bridge returned HTTP 401. Re-copy the token from the bottom of the
install.sh banner — terminal soft-wraps sometimes split it across
lines. Or sudo cat /etc/hermes-voice-bridge/config.toml on the
server and copy from there.
Likely ECONNREFUSED. Check on the server:
systemctl status hermes-voice-bridge
curl http://localhost:8765/healthz # → {"ok": true, ...}If the service is dead, look at journalctl -u hermes-voice-bridge -n 80.
You typed the wrong path (HTTP 404). The bridge mounts WS on /ws
only. The client auto-appends /ws if missing (see
WebSocket-Client#url-normalisation) — this message means the URL
plus the auto-/ws still 404s.
You're connecting via wss:// to a server with a self-signed cert.
Either use ws:// (only safe on a trusted LAN) or get a proper
certificate.
The whisper.cpp binary isn't on disk. You have three options:
- Easiest: open Definições → Reconhecimento and switch to "OpenAI Whisper API". Paste your API key.
-
Homebrew (macOS):
brew install whisper-cpp. The app will auto-detect it on PATH at next startup. -
From source: build
whisper.cpp and put the
resulting
whisper-cli(formerlymain) binary at<userData>/whisper/bin/whisper. The model fileggml-base.binauto-downloads from Hugging Face on first use.
(<userData> is ~/Library/Application Support/Voice Gateway on
macOS, ~/.config/Voice Gateway/ on Linux, %APPDATA%\Voice Gateway\
on Windows.)
See Speech-To-Text#whisper-local-whispercpp for the binary discovery order.
The default autoInstall: true config means the app should create a
Python venv at <userData>/piper/venv on first use. If that fails:
- Easiest: switch to ElevenLabs in Definições → Voz. Paste an API key.
-
Manual:
pip3 install --user piper-ttsin a terminal, then restart the app.
See Text-To-Speech#auto-install-the-venv-dance for what should happen on first run.
The most common cause is the bridge sending response_end
synchronously with response_text final=true. The orchestrator
holds the FSM in SPEAKING while local TTS is synthesising and
defers the response_end dispatch until TTS emits its own end
event — see
Conversation-Orchestrator#the-response_end-race for details.
If you still see no audio after that:
-
Confirm Piper is producing chunks. Open
~/Library/Logs/Voice Gateway/main.logand look for[VG] piper:debug lines (sample-output) immediately afterresponse_text final=true. - Confirm chunks reach the renderer. Open DevTools (Cmd+Option+I) on the main window, watch the console for "tts_chunk" logs.
-
Confirm AudioContext is running. In DevTools console:
document.querySelector('audio') // null is expected — we use AudioBufferSourceNode // Better: getAudioContextState() // exposed by AudioPlayback in debug builds
- The AudioContext is suspended. Chromium's autoplay policy suspends contexts that aren't created during a user gesture. Make sure you clicked the PTT button (don't just press the global hotkey for the very first turn — the gesture has to be inside the page).
Your bridge is talking to a Hermes that requires an API key, but you
didn't set one in the install. Edit
/etc/hermes-voice-bridge/config.toml:
[hermes]
api_key = "sk-..."then sudo systemctl restart hermes-voice-bridge. The desktop will
reconnect automatically.
Error: bridge round-trip timed out after 90000 ms — trace: welcome, thinking
This means the bridge accepted the request, sent thinking, but
Hermes never produced text within 90 s. Two real causes:
-
Hermes is slow on cold start. Some models take 30–60 s to
warm up after
systemctl restart hermes. Wait a minute, retry. -
Hermes returned 200 but with an empty body. Check
journalctl -fu hermes-voice-bridge— you'll see one of:The third line means the fallback path saved you. If you see "non-stream fallback parsed but no message content" the model is genuinely producing nothing — check the agent's own log.hermes responded 200 (Content-Type=text/event-stream) hermes stream done — 0 delta(s), 0 chars total hermes non-stream fallback OK — N chars
Override the timeout for very-slow setups:
VG_BRIDGE_TIMEOUT_MS=180000 \
VG_BRIDGE_URL=ws://… VG_BRIDGE_TOKEN=… \
npm test -- tests/integration/bridge-text-roundtrip.test.tsThe Python runner couldn't import its dependencies. Install them:
python3 -m pip install -r resources/python/requirements.txt(or in a venv if you prefer). Then toggle the activation mode off and back to Wake Word in Definições.
Lower the threshold in
wake_word_runner.py
(default 0.5) or try a different model — "Hey Jarvis" trains better
than "Computer".
See Wake-Word-Detection for the JSON line protocol.
- The renderer's audio worklet downsamples to 16 kHz with a simple linear interpolator (see Audio-Pipeline#capture). If you see distortion, try unchecking autoGainControl in your OS sound settings.
- TTS playback for ElevenLabs decodes the full MP3 once the stream ends. For low-latency TTS, prefer Piper (PCM streaming).
- A high latency indicator in the header (>300 ms) usually means Wi-Fi packet loss between the desktop and the bridge. Hard-wire the server if you can.
You hit the PTT-release race documented in Audio-Pipeline#the-ptt-press-release-race. Should be fixed in the shipping version; if you see it on the latest, file an issue with the log line preceding the error (likely shows a fast press → release pattern).
System Settings → Privacy → Microphone → toggle Voice Gateway on. If the toggle is missing entirely, the app's bundle signature is broken — see macOS-Permissions for the full triage.
The bundle's Designated Requirement changed (rebuild signed differently).
Run codesign -dr- "/Applications/Voice Gateway.app" — the identifier
should print as dev.voicegateway.app. If it says Electron, the
post-build re-sign didn't happen — see
Build-And-Packaging#macos-code-signing.
- Default is
Cmd+Shift+H(macOS) /Ctrl+Shift+H(Linux/Windows). If another app already owns that combo, Electron silently fails to register — the main-process log shows[VG] global hotkey already in use. Change the binding in Definições → Ativação. - On macOS, the first time you press the hotkey the system prompts for "Input Monitoring" permission. Grant it once.
# macOS
rm -rf "~/Library/Application Support/Voice Gateway"
# Linux
rm -rf ~/.config/Voice\ Gateway
# Windows
rd /s /q "%APPDATA%\Voice Gateway"Then relaunch. The pairing wizard appears again.
The Settings panel also has an Avançado → Factory reset button that does the same thing without leaving the app.
[VG] hermes reconnect in 500 ms (attempt 1) is normal once or twice
after the laptop wakes from sleep. If it goes past attempt 6 you're
hitting the cap (~16 s between tries) and the server is genuinely
down. Same triage as the pairing failure above.
See WebSocket-Client#reconnect-backoff for the full ladder.
Symptom: npm run build:mac aborts after electron-vite build finishes
with something like:
Error: Cannot find module '/.../node_modules/builder-util/node_modules/fs-extra/lib/index.js'.
Please verify that the package.json has a valid "main" entry
code: 'MODULE_NOT_FOUND',
requestPath: 'fs-extra'
The package.json referenced in the error is usually present — only
one or two files inside the package have vanished. The root cause is
typically the repo living on an external volume whose filesystem
(exFAT, MS-DOS) doesn't preserve POSIX metadata reliably; individual
nested files drop out without the surrounding tree being broken. APFS
volumes don't exhibit this.
The tools/build-doctor.cjs pre-flight (wired into build:mac,
build:linux, build:win) detects the most commonly affected paths
and prints the exact recovery command — usually:
rm -rf node_modules/<pkg>/node_modules/<dep>
npm install…which takes ~10 s and avoids the alternative (rm -rf node_modules && npm ci) that can need >10 min and several GB of free disk.
You hit a path the doctor doesn't know about yet. Two steps:
- Read the failing path out of the error message.
- Add it to
CRITICAL_FILESintools/build-doctor.cjsin the same PR that documents the new failure mode.
See Build-And-Packaging#build-doctor-pre-flight for the rationale.
Logs live at:
- macOS:
~/Library/Logs/Voice Gateway/main.log - Linux:
~/.config/Voice Gateway/logs/main.log - Windows:
%APPDATA%\Voice Gateway\logs\main.log
When opening an issue please include the last ~100 lines plus the output of:
codesign -dv "/Applications/Voice Gateway.app" # macOS only
systemctl status hermes-voice-bridge # on the server
journalctl -u hermes-voice-bridge -n 40File issues at https://github.com/VivaldiCode/voice-gateway/issues.
Voice Gateway — VivaldiCode/voice-gateway. MIT licensed. Wiki sources live under docs/; run ./docs/sync-wiki.sh to publish.
Getting started
Architecture
- Architecture — system overview
- State-Machine — conversation FSM
- Conversation-Orchestrator — main glue
- WebSocket-Client — Hermes connection
- IPC-Layer — main ↔ renderer
- Settings-And-Storage — config persistence
Audio
- Audio-Pipeline — capture & playback
- Speech-To-Text — STT adapters
- Text-To-Speech — TTS adapters
- Wake-Word-Detection — openWakeWord
Server
- Hermes-Voice-Bridge — Python bridge
- Protocol — WebSocket spec
Platform
- Build-And-Packaging — electron-builder
- macOS-Permissions — TCC, signing
- Renderer-UI — React components
Project
- Testing-Guide — unit, integration, E2E
- Development-Guide — contributing
- Glossary — terms