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:

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

Note

On macOS, if you recently changed the default output device (e.g., plugged in headphones), brūhi may still be using the previous device. Re-select the device in the Audio Devices panel.

---

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:

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

Note

MIDI support may not be enabled in all builds. Check the About screen for feature flags.

---

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:

1. Check the Icecast server logs for the reason (too many listeners, source timeout, etc.).
2. Increase the Icecast <source-timeout> setting in icecast.xml.
3. Check network stability between brūhi and the Icecast server.
4. 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

Error: ICECAST_SOURCE_PASSWORD must be explicitly configured in production mode

Cause: ICECAST_SOURCE_PASSWORD is missing or commented out in your .env file while running in production mode.

Fix: Ensure your .env contains explicit passwords for Icecast:

ICECAST_SOURCE_PASSWORD=your_secure_password
ICECAST_ADMIN_PASSWORD=your_secure_password
ICECAST_RELAY_PASSWORD=your_secure_password

Or auto-generate them:

echo "ICECAST_SOURCE_PASSWORD=$(openssl rand -hex 16)" >> .env
echo "ICECAST_ADMIN_PASSWORD=$(openssl rand -hex 16)" >> .env
echo "ICECAST_RELAY_PASSWORD=$(openssl rand -hex 16)" >> .env
docker compose up -d

---

Error: fatal: not a git repository

Cause: The ~/bruhi-cloud directory on production servers is not a Git repository — it was initialized by install.sh.

Fix: Use curl to refresh files instead of git pull:

cd ~/bruhi-cloud
curl -fsSL https://raw.githubusercontent.com/bruhi-technologies/bruhi-deploy/main/docker-compose.yml -o docker-compose.yml
docker compose pull
docker compose up -d

---

Error: Permission denied: /tmp/bruhi-audio/api_token

Cause: Docker mounted the bruhi_audio_sockets volume with root ownership, preventing the internal unprivileged process from writing tokens.

Fix: Update to the latest image tag (v0.10.1+), or fix socket permissions manually:

docker compose exec bruhi-cloud chown -R bruhi:bruhi /tmp/bruhi-audio
docker compose restart bruhi-cloud

---

Container keeps restarting (Crash Loop)

Steps:

# Check startup logs for error details
docker compose logs --tail=50 bruhi-cloud

# Check container exit status
docker compose ps

Common Cause	Resolution
Missing required env variable	Check .env — ensure BRUHI_URL, DOMAIN, and passwords are set
Port 8000 already bound	Run sudo lsof -i :8000 on host; change PORT= in .env
Database migration error	Run docker compose exec bruhi-cloud sqlite3 /app/data/bruhi.db "PRAGMA integrity_check;"

---

WebRTC connection drops after a few seconds

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

Steps:

1. Ensure the brūhi dashboard is served over HTTPS (required for WebRTC audio streams in all browsers).
2. Check that firewall allows WebRTC UDP return traffic (49152–65535).
3. Ensure server clock and client browser are synchronized.

---

bruhi-audio engine runner not starting

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

Symptom	Cause	Fix
Could not connect to bruhi-audio API	Daemon not listening on internal port 7700	Check container logs: docker compose logs bruhi-cloud
Could not open output to Icecast	Incorrect Icecast password or host port	Check ICECAST_SOURCE_PASSWORD and output settings
harbor: Address already in use	Harbor port conflict	Verify harbor port availability (8100+)

---

Stream shows as offline even though DJ is live

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

Steps:

1. Verify the Icecast mountpoint is active by opening http://your-server:8010/status.xsl in a browser.
2. Check that the Icecast port (8010) is open in your cloud firewall / AWS security group.
3. Confirm the output settings in Admin → Stations → Outputs match your configured ICECAST_SOURCE_PASSWORD.

---

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 and Rust audio engine take a few seconds to complete startup and health checks.

Fix:

# Check health status
docker compose ps
# Inspect application logs
docker compose logs bruhi-cloud