Troubleshooting

July 31, 2026 · View on GitHub

Connection issues

`RuntimeError: NodeIdentity not set`

The satellite requires key, password, and host to connect. Either:

Run hivemind-client set-identity --key ... --password ... --host ...
Or pass --key, --password, and --host directly on the command line

Cannot connect / WebSocket error

Confirm hivemind-core is running on the server and listening on the expected port (default 5678).

Check that the host and port are correct:

hivemind-mic-sat --host 192.168.1.10 --port 5678 ...

Test basic connectivity:
```
nc -z 192.168.1.10 5678
```
Check that you created the access_key with hivemind-core add-client and that you use the correct key/password pair.

SSL / self-signed certificate

If the hive uses wss:// with a self-signed certificate, the client may reject it. Either:

Add the certificate to the system trust store on the satellite.
Use a plain ws:// connection on a private network.

When you pass the host manually, include the scheme:

hivemind-mic-sat --host wss://myhive.example.com --port 443 ...

No audio input (microphone not working)

Check that a microphone plugin is installed and configured:
```
arecord -l
```

Test the microphone directly:

arecord -D hw:1,0 -f S16_LE -r 16000 -d 3 test.wav && aplay test.wav

Ensure mycroft.conf has the correct microphone.module and device string.
Check permissions. The user running hivemind-mic-sat must be in the audio group:
```
sudo usermod -aG audio $USER
```

Audio is streaming but the hive does not process it

Symptom: You see Speech start, initiating audio transmission in the log but never UTTERANCE: ....

The server is missing hivemind-audio-binary-protocol. The default hivemind-core does not include STT/TTS/wakeword processing. Install hivemind-audio-binary-protocol on the server and restart hivemind-core.

No TTS playback (no audio output)

Test speakers independently:
```
speaker-test -t wav -c 2
```
Check that ovos-audio is installed. It ships with requirements.txt, so it should be present.
If ALSA reports Device or resource busy, another process holds the audio device. Check with:
```
fuser /dev/snd/*
```
Check the log for TTSHandler messages:
- Received TTS: <filename> means the satellite received audio and wrote it to /tmp/.
- If this line is absent, the hive did not send TTS audio back. Check the server-side TTS configuration.
Verify the speak:synth round-trip: the satellite sends speak:synth to the hive, which should respond with a binary TTS payload. If the hive TTS plugin is not configured server-side, no audio comes back.

TTS received but not played (stuttering or silent playback)

The PlaybackThread writes received TTS to /tmp/<hash>.wav. Check that /tmp is writable and has free space.
If you use a USB audio dongle, confirm ALSA recognizes it as a playback device (aplay -l).

VAD triggers too eagerly or not at all

Too eager (constant streaming): try a more selective VAD plugin (for example ovos-vad-plugin-silero) or tune the VAD aggressiveness in mycroft.conf.
Not triggering (no Speech start log lines): check microphone levels with alsamixer and raise input gain if needed. Try ovos-vad-plugin-webrtcvad, which can be more sensitive.

`mycroft.audio.play_sound` sound not found

The satellite resolves snd/<name> URIs against its bundled resource directory. Only the three bundled files (acknowledge.mp3, error.mp3, start_listening.wav) are available. Custom sound URIs must be absolute paths accessible on the satellite filesystem.

Diagnosing with verbose logging

Set the log level to DEBUG in mycroft.conf:

{
  "log_level": "DEBUG"
}

Or run with the environment variable:

OVOS_LOG_LEVEL=DEBUG hivemind-mic-sat

PHAL not starting

PHAL is optional. If ovos-PHAL is not installed, the satellite logs:

PHAL is not available

and continues without it. This is not an error. Install ovos-PHAL only if you need hardware plugin support.

← Testing · Home