Troubleshooting

brūhi Desktop

App won’t start on Linux

Symptom: The app crashes immediately on launch, or shows a blank window.

Cause: Missing libwebkit2gtk-4.1 or libwebkit2gtk-4.0.

Fix:

# Ubuntu / Debian
sudo apt install libwebkit2gtk-4.1-0

# Older Ubuntu / Debian
sudo apt install libwebkit2gtk-4.0-37

# Fedora
sudo dnf install webkit2gtk4.1

No audio output / can’t hear anything

Symptom: Tracks play (position advances) but no sound.

Steps:

Go to System → Audio Devices.
Check that the Output bus is set to the correct device.
Check that system volume is not muted.
On Linux: check that PulseAudio or PipeWire is running.

Audio device not found after connecting hardware

Symptom: A USB audio interface or headset appears in system settings but not in brūhi.

Cause: brūhi enumerates audio devices at startup. Hot-plugged devices may not appear automatically.

Fix: Restart brūhi after connecting the device. Hot-plug re-enumeration is on the roadmap.

JACK not detected on Linux

Symptom: JACK does not appear as an audio device option.

Cause: JACK must be running before brūhi starts.

Fix:

# Start JACK first
jackd -d alsa -r 48000 &

# Then start brūhi

If using PipeWire-JACK:

pw-jack bruhi-desktop

MIDI device not detected

Symptom: A MIDI controller is connected but not showing in the MIDI mapping panel.

Steps:

Confirm the MIDI device is detected by the OS (aconnect -l on Linux, Audio MIDI Setup on macOS).
In brūhi, go to System → MIDI and check the port list.
If still not visible, restart brūhi (MIDI ports are enumerated at startup).

SRT output fails to connect

Symptom: SRT output shows as “connecting” or immediately disconnects.

Cause 1: libsrt is not installed on the host.

Fix: Install libsrt-dev (Linux) or the SRT binaries (Windows/macOS), then rebuild brūhi from source with --features srt.

Cause 2: Firewall blocking the SRT port (default 9000 UDP).

Fix: Open the UDP port in your firewall: sudo ufw allow 9000/udp

Broadcast output disconnects repeatedly

Symptom: Icecast/Shoutcast output reconnects every few minutes.

Steps:

Check the Icecast server logs for the reason (too many listeners, source timeout, etc.).
Increase the Icecast <source-timeout> setting in icecast.xml.
Check network stability between brūhi and the Icecast server.
Verify the Icecast <max-sources> limit has not been reached.

SQLite database errors on startup

Symptom: Error dialog about database corruption or locked file.

Fix:

# macOS
cd ~/Library/Application\ Support/bruhi/

# Linux
cd ~/.local/share/bruhi/

# Windows
cd %APPDATA%\bruhi\

# Backup and remove the database to reset
cp bruhi.db bruhi.db.bak
rm bruhi.db

Restarting brūhi will create a fresh database. The library will need to be rescanned.

brūhi Cloud

WebRTC connection drops after a few seconds

Symptom: DJ clicks “Go Live” and the stream appears active, but audio drops after 10–30 seconds.

Cause: WebRTC ICE renegotiation is not yet fully stable for connections longer than ~24 hours. Short drops during the same session may indicate NAT or firewall issues.

Workaround:

Ensure the br\u016bhi dashboard is served over HTTPS (required for WebRTC in most browsers).
Check that no firewall is blocking WebRTC ICE candidates (UDP ports typically in the 49152–65535 range).
Consider restarting the station and reconnecting if the connection drops.

GStreamer pipeline crash

Symptom: Live audio stops and the station log shows a GStreamer error.

Steps:

Retrieve the logs: GET /api/stations/{id}/logs?lines=200
Look for ERROR or CRITICAL in the GStreamer output.
Restart the station: POST /api/stations/{id}/restart

Common causes:

Error	Cause	Fix
`Could not initialize audiomixer`	GStreamer plugins missing	Rebuild or use the official Docker image
`No such element 'webrtcbin'`	Missing `gstreamer1.0-plugins-bad`	Add to Dockerfile
`Stream ended unexpectedly`	Client disconnected without ICE teardown	Restart station; session cleanup in progress

Port conflict when starting a station

Symptom: POST /api/stations/{id}/start returns an error about a port already in use.

Cause: The harbor port (8100 + N − 1) is already occupied by another process.

Steps:

# Find what's using the port (example: port 8100)
lsof -i :8100
# or
ss -tlnp | grep 8100

If the port is occupied by a previous br\u016bhi process, restart the container:

docker compose restart

Liquidsoap not starting

Symptom: GET /api/stations/{id}/logs shows Liquidsoap errors immediately after start.

Common causes:

Symptom	Cause	Fix
`Syntax error in station.liq`	Invalid `.liq` file	Check station config for typos
`Could not open output to Icecast`	Wrong Icecast password or host	Check `icecast.xml` and `.liq` file match
`harbor: Address already in use`	Port conflict	Check port availability (see above)
`File not found: /app/playlists/station-N.m3u8`	Playlist file not created yet	Add tracks via the dashboard or API

Stream shows as offline even though DJ is live

Symptom: DJ is connected and on air in the dashboard, but listeners cannot connect.

Steps:

Verify the Icecast mountpoint is active: open http://your-server:8005/status.xsl in a browser.
Check the harbor port (8100 + N − 1) is open in the firewall.
Confirm the Icecast output in the station’s .liq file has the correct mount, host, and password.
Check station logs for output errors: GET /api/stations/{id}/logs.

Dashboard shows “Connection refused” after deploy

Symptom: Opening http://your-server:8000 shows a connection error immediately after docker compose up.

Cause: The FastAPI server takes a few seconds to start. The container may not have fully initialized.

Fix:

# Wait for healthy status
docker compose ps
# Should show "healthy" after ~15 seconds

# Or check logs
docker compose logs bruhi

If it stays unhealthy, check docker compose logs for startup errors.