Troubleshooting
The installer and the app name the problem; this page says what to do. The bridge's log has no tokens, audio or transcripts, only stages, lengths and timings:
| Platform | Log | Service status |
|---|---|---|
| Linux | journalctl -u hermes-car-voice-bridge | systemctl status hermes-car-voice-bridge |
| macOS | ~/Library/Application Support/Car Voice Bridge/logs/bridge.log (and launchd.log next to it) | launchctl print gui/$(id -u)/app.carvoice.bridge |
| Windows | %LOCALAPPDATA%\Car Voice Bridge\logs\bridge.log | schtasks /Query /TN "Car Voice Bridge" /V /FO LIST |
To restart the bridge after a change to bridge.env: sudo systemctl restart hermes-car-voice-bridge on Linux, launchctl kickstart -k gui/$(id -u)/app.carvoice.bridge on macOS, and on Windows schtasks /End /TN "Car Voice Bridge" followed by schtasks /Run /TN "Car Voice Bridge". curl is on all three (curl.exe in PowerShell).
The three most likely problems
Hermes is not reachable
The installer says Hermes: not reachable at http://127.0.0.1:8642, the app says "Hermes is not reachable.", and curl -s http://127.0.0.1:8787/readyz shows "hermes":"unreachable".
- The Hermes API server is not running. It runs inside the Hermes gateway: start it with
hermes gateway, or restart it withhermes gateway restart(or/restartin a chat with Hermes); it reportsAPI server listening on http://127.0.0.1:8642. A gateway that was already running when the installer addedAPI_SERVER_ENABLEDandAPI_SERVER_KEYneeds a restart before it uses them. Hermes cannot restart the gateway it runs in itself, so when Hermes set things up through a messaging app, send/restartyourself. - Hermes listens on another port or address than the bridge expects: compare
API_SERVER_HOSTandAPI_SERVER_PORTin Hermes'.envwithHERMES_API_BASE_URLin the bridge'sbridge.env(where it is), then restart the bridge (see the top of this page). - The bridge checks Hermes at most every 30 seconds, so
/readyzcan lag behind for half a minute.
/readyz only checks that the API server answers, not the key. "Hermes rejected the bridge key." in the app means HERMES_API_KEY in bridge.env differs from API_SERVER_KEY in Hermes; put the same key in both and restart the bridge. A re-run of the installer warns about this too.
The phone cannot reach the bridge
The app says "Your bridge is offline" (the phone reached Car Voice's relay, but the bridge did not answer) or "The bridge is not reachable" (the phone did not get that far).
- "Your bridge is offline": the computer with the bridge is off, asleep or offline, or the bridge does not run (keep the computer awake; its service status: see the top of this page). On that computer,
curl -s http://127.0.0.1:8787/readyzshould show"link":"online". Then ask the bridge to call itself through the relay, as a phone would:hermes_voice_bridge link-check(the installer's summary shows the full command for your computer; on Linuxsudo systemd-run --pipe --wait --quiet -p EnvironmentFile=/etc/hermes-car-voice/bridge.env -p User=carvoice -p WorkingDirectory=/opt/hermes-car-voice/backend /opt/hermes-car-voice/.venv/bin/python -m hermes_voice_bridge link-check). It prints"link": "ok"when phones can reach it. "link":"connecting"stays, or link-check fails: the computer cannot reachrelay.carvoice.app. The bridge needs outgoing HTTPS (TCP 443) to it; outgoing UDP helps direct connections but is not required. A company firewall or proxy can block it. The log showslink: …lines with the reason."link":"unavailable": the bridge could not start the link, usually because theirohpackage is missing (run the installer again) or the data folder is not writable. The log says which."link":"off":HERMES_BRIDGE_IROH=offis set inbridge.env; the phone then needs your own HTTPS address.- "The bridge is not reachable": check the phone's internet connection (mobile data or Wi-Fi). A network that blocks unknown services (some public Wi-Fi) can block the relay too; try mobile data.
- The app's bridge address must be the bridge's current ID. After
hermes_voice_bridge id --rotate, or a new installation with--purgein between, pair again.
With your own HTTPS address (advanced): in the phone's browser, on mobile data, open https://<your bridge address>/healthz. It should show {"status":"ok"}.
- Tailscale: the Tailscale app on the phone must be signed in to the same tailnet and connected. On the bridge machine,
tailscale serve statusshould list a proxy tohttp://127.0.0.1:8787. HTTPS certificates must be enabled for the tailnet (Enabling HTTPS). - Cloudflare Tunnel or a reverse proxy: its service or upstream must be
http://127.0.0.1:8787, and it has to run on the bridge machine.curl -s http://127.0.0.1:8787/healthzon that machine tells whether the bridge itself answers (its service status: see the top of this page). {"status":"ok"}in the browser but the app still fails: the address in the app must be exactly that origin (https://host[:port], no path). Pair again and scan the new code.
An unreachable bridge never locks you out: the next question simply tries again.
Speech recognition is still loading
The installer says Speech recognition: still loading the model, first start downloads a few hundred MB, and /readyz shows "stt":"loading". On its first start the bridge downloads the Whisper model; after that it only loads it from disk. A question asked in the meantime waits for the model. Wait a few minutes and check /readyz again. If it stays loading, look for stt: preload failed in the log: the machine may have no internet access or too little memory (Whisper small needs roughly 400 to 700 MB). An OpenAI-compatible transcription service avoids the download; see Answers are slow.
What the installer says
| The installer says | What to do |
|---|---|
| Car Voice needs Python 3.11 or newer | Install Python 3.11 or newer and run the installer with it: from your distribution on Linux (e.g. sudo python3.11 car-voice-bridge-0.7.0/backend/install.py), from python.org or Homebrew on macOS (the python3 that comes with macOS is older), from python.org on Windows (then py -3.12 …\install.py). |
| Run the installer as root | Linux only: run it with sudo, as the user that runs Hermes. |
| Run the installer without sudo on macOS | On a Mac the bridge runs as you, like Hermes: run python3 …/install.py without sudo. |
| This is the macOS plan, but this computer is not a Mac (or the Windows or Linux variant) | --platform only goes with --dry-run; a real run uses the platform it runs on. |
| This machine does not run systemd | Linux without systemd: if this is the container where your Hermes gateway runs, add --container (container mode); otherwise install the bridge by hand or with Docker. In WSL2, switch systemd on first (setup: WSL2). |
| No Hermes found in … (HERMES_HOME) | Container mode: the installer runs where Hermes' data folder is not, usually a separate sandbox for Hermes' terminal. Run it in the Hermes container itself (docker exec -it <container> sh), or set HERMES_HOME to Hermes' data folder. |
| This Linux runs systemd, so the normal installation fits | --container was given on a machine with systemd: leave it out and run sudo python3 …/install.py. |
| This container has … GB of memory | Container mode: local speech recognition would not fit well next to Hermes. Use a speech recognition service with its key in a file you create yourself: (umask 077 && cat > ~/carvoice-stt.key), paste the key, Enter, Ctrl-D, then --stt openai --stt-base https://api.groq.com/openai/v1 --stt-key-file ~/carvoice-stt.key. Without a key: --stt-model base (smaller, a little less accurate). Nothing was changed. |
| --stt-key-file … does not exist, is empty, or must hold the key alone | Create the file yourself (never in a chat): in a terminal (umask 077 && cat > ~/carvoice-stt.key), paste only the key, press Enter, then Ctrl-D; on Windows notepad "%USERPROFILE%\carvoice-stt.key", paste only the key, save. Nothing was changed. |
| --stt-key-file … can be read or changed by other users | Linux and macOS: make it private with chmod 600 <file>, then run the installer again. Nothing was changed. (Windows does not check this: a file in your user folder is private already.) |
| Python's venv module is missing | sudo apt install python3-venv on Debian and Ubuntu, then run the installer again. On macOS and Windows, use a Python from python.org (or Homebrew on macOS), which includes it. |
| No Hermes Agent found | Install Hermes Agent first, or run the installer with --hermes-env PATH (Hermes' .env file) or --hermes-url http://127.0.0.1:8642. |
| Hermes' API server is not switched on yet | Answer yes to let the installer add API_SERVER_ENABLED=true and a new API_SERVER_KEY, or add them yourself (setup step 1). Then restart the gateway (hermes gateway restart, or /restart in a chat with Hermes). Without a terminal the answer is no; add --yes. |
| Hermes keeps API server settings in …config.yaml | Run the installer with --hermes-url http://127.0.0.1:8642 (or your port) and type the API server key when asked. |
| Hermes listens on … (API_SERVER_HOST) | The bridge reaches Hermes only on the same machine or over HTTPS. Keep API_SERVER_HOST at its default 127.0.0.1, or use --hermes-url https://…. |
| These bridge settings would not work | The message names the setting, e.g. an --stt-base that is not https://. Nothing was changed. |
| The bridge configuration check failed | The message names the setting in bridge.env. Fix it and run the installer again. On Linux the running bridge was not restarted; on macOS and Windows the previous code was put back and started again. |
| The bridge did not answer on …/healthz | The last log lines are shown above the message (on Windows also the scheduled task's status). More in the log, see the table at the top of this page. |
| launchctl bootstrap … failed | macOS refused to load the LaunchAgent; its message is shown. Check that you ran the installer as yourself, not with sudo, in a normal login session. |
| Registering the scheduled task (schtasks /Create) failed | Windows refused to create the task; its message is above. A company policy can block scheduled tasks; ask whoever manages the PC. |
| … is in use and cannot be replaced | Windows: a program still uses the bridge's files. Close terminals or editors opened in its folder and run the installer again. |
| phone link: not reachable through relay.carvoice.app yet | Pairing still works; the phone connects as soon as the bridge reaches the relay. If it stays like this, see The phone cannot reach the bridge. |
| tailscale serve did not succeed | Only with --tailscale. Tailscale's own message is shown above it, unchanged. Usually HTTPS certificates are not enabled for the tailnet yet (Enabling HTTPS). Or pair by bridge ID instead: sudo python3 /opt/hermes-car-voice/backend/install.py --pair. |
| A phone named 'phone' is already paired | Answer yes to give it a new token (the old one stops working), add --replace, or pair another phone with --name tablet. |
| HERMES_API_KEY … differs from API_SERVER_KEY | See Hermes is not reachable: put the same key in both. |
| sha256sum: WARNING: 1 computed checksum did NOT match | The download is incomplete or damaged. Delete the archive, download it and SHA256SUMS again and check again; do not install a file that fails the check. |
Pairing codes
| The app says | What to do |
|---|---|
| This pairing code is wrong, expired or already used. | A code works once, for 10 minutes, and only the newest code for a phone name works. Ask Hermes for a new one, or run sudo python3 /opt/hermes-car-voice/backend/install.py --pair --code-only --replace. Check the address too: it must be the bridge ID (iroh:…) or HTTPS address printed with the code. |
| Too many attempts. | The bridge allows 10 attempts per address in 10 minutes and, after 20 wrong codes in 10 minutes, cancels every open code. Wait a few minutes, then pair again with a new code. |
| This bridge is too old for pairing codes. | The bridge predates 0.5.0. Update it, or scan the QR code that --pair shows without --code-only. |
| Your bridge is offline. / The bridge is not reachable. | See The phone cannot reach the bridge. |
| This QR code needs a newer version of Car Voice. | A QR code with a bridge ID (bridge 0.7.0) needs app 0.7.0 or newer: update the app from Google Play. |
In a container: no bridge after a restart or a new Hermes image
In container mode the Hermes gateway starts the bridge (its gateway hook hooks/car-voice-bridge in Hermes' data folder). Look in car-voice/logs/supervise.log there (/opt/data/car-voice/logs/supervise.log in Hermes' image):
- "Car Voice bridge not started: … is missing (a new Hermes image?)": the new image took the Python the bridge's environment was made with. Run the installer again (
python3 /opt/data/car-voice/backend/install.py); it makes the environment again and keeps your settings and paired phones. - No new lines at all: the gateway did not load the hook. The gateway's log shows
[hooks] Loaded hook 'car-voice-bridge'when it does. Check thathooks/car-voice-bridge/HOOK.yamlandhandler.pyare there, and that the gateway runs (hermes gateway); without the gateway there is no API server for the bridge either. - "the bridge stopped (exit …)": the bridge's own log,
car-voice/logs/bridge.log, says why. Exit -9 often means the container ran out of memory; see the memory note under Hermes in Docker or on a hosted server.
Car Voice works, but not after a while
The computer with Hermes and the bridge went to sleep, or (macOS, Windows) you were logged out. The bridge only answers while the computer is on and awake, and on macOS and Windows it runs in your login session. See Keep the computer awake. In WSL2, WSL itself may have stopped: see setup: WSL2.
"Setup incomplete" on the home screen
You skipped a setup step. Tap Finish setup: it opens the missing step (microphone or connection).
Hermes hears nothing / "The microphone produced no sound"
- Check that the microphone is allowed: Settings › Voice › Microphone. Android Auto cannot ask for it in the car, so allow it on the phone first. If Android no longer asks, open the app settings (Car Voice offers the button) and allow the microphone under Permissions.
- With Android Auto connected, use Talk on the car screen. Android Auto (or the Assistant) can mute the phone's own microphone while it projects; the app then says another app holds the microphone.
- The small line under the status shows what the last attempt picked up (source, peak level, decision). "No sound" means the microphone delivered silence; "no speech" means it heard sound but no question.
"The token was rejected"
The bridge no longer accepts the saved token (it was replaced with --replace, removed from the tokens file, or belongs to another bridge). Pair again (sudo python3 /opt/hermes-car-voice/backend/install.py --pair, see setup step 5) and connect in Settings › Connection with Enter pairing code or Scan QR code.
"Your bridge is offline" / "The bridge is not reachable"
See The phone cannot reach the bridge.
"The bridge must first be updated"
The address answers, but without the /voice/v2 API this app needs. Update the bridge (see Updating the bridge). If Settings says "Your bridge ignores this setting until it is updated" under Spoken replies, the bridge works but predates short and full replies.
Hermes errors
| The app says | Cause |
|---|---|
| Hermes rejected the bridge key. | HERMES_API_KEY in the bridge does not match API_SERVER_KEY in Hermes. |
| Hermes is not reachable. | The Hermes API server is not running, or HERMES_API_BASE_URL is wrong. /readyz then shows "hermes":"unreachable". |
| Hermes is busy with other tasks; try again in a moment. | Hermes answered 429, for example because its limit on concurrent runs was reached. |
| Hermes took too long; I stopped the task. | The run took longer than HERMES_TURN_TIMEOUT_SECONDS (default 600). |
| Speech recognition … | The STT provider failed: check its address and key, or switch to local Whisper. |
For anything inside Hermes itself, see the Hermes documentation.
Answers are slow
Local Whisper (small) needs several seconds per question on a small CPU. An OpenAI-compatible transcription service (HERMES_BRIDGE_STT_PROVIDER=openai, or --stt openai for a new installation) is usually well under a second; your recorded questions then go to that service. The rest of the time is Hermes working; the car screen shows what it is doing.
The spoken answer stops early
The voice says "The full text is in the app": the reply was longer than the safety net (HERMES_BRIDGE_SPEECH_MAX_CHARS_SHORT, 700 characters for short replies; HERMES_BRIDGE_SPEECH_MAX_CHARS, 3000 for full replies), or it contained code, which is never read aloud. Choose Full in Settings › Voice › Spoken replies for complete answers, or raise the value on the bridge. Bridges before 0.4.0 cut full replies at 450 characters; a HERMES_BRIDGE_SPEECH_MAX_CHARS line in bridge.env keeps its own value after an update.
Wrong language
Car Voice listens and speaks in the phone's language. If you speak a different language from the one your phone is set to, pick yours in Settings › Voice › Language.
No Car Voice in Android Auto
- Car Voice must be installed from Google Play to appear in a real car. A sideloaded APK does not appear, and the Android Auto developer option "Unknown sources" does not apply to this kind of app (Google's testing guide). Testers use the Play internal test track or Internal App Sharing.
- Connect the phone to Android Auto and look among the apps on the car screen. If you customised the Android Auto launcher, check that Car Voice is not hidden.