Troubleshooting

Troubleshooting

Audio Issues

No Sound / Audio Plays Through Wrong Device

Symptoms: Audio plays through laptop speakers instead of your DAC, or no sound at all.

Fix:

1. Go to Settings > Audio
2. Verify the correct Output Device is selected
3. If using PipeWire, ensure your DAC is set as the default sink:

   # List available sinks
   pactl list sinks short
   
   # Set your DAC as default
   pactl set-default-sink <sink-name>

4. Restart QBZ after changing the audio device

Audio is Resampled (DAC Shows Wrong Sample Rate)

Symptoms: Your DAC display shows 48000 Hz regardless of the track's actual sample rate.

Fix:

• Switch to ALSA Direct backend for guaranteed bit-perfect output
• If using PipeWire, enable Force Bit-Perfect in Settings > Audio
• Verify with a known Hi-Res track (96 kHz or 192 kHz) — your DAC display should match

Crackling or Stuttering Audio

Possible causes:

• Buffer too small — increase Stream Buffer in Settings > Audio
• System under load — close resource-heavy applications
• USB DAC power — try a powered USB hub or a different USB port

DAC Not Detected

1. Verify the DAC is connected and powered on
2. Check if the system sees it:

   # List ALSA devices
   aplay -l
   
   # List PipeWire devices
   pw-cli list-objects Node

3. Try unplugging and reconnecting the DAC
4. Restart QBZ

Graphics Issues

Black Screen, Flickering, or Rendering Glitches

QBZ uses hardware-accelerated rendering by default. Some GPU/driver combinations may cause issues.

Quick fixes (in order of severity):

# 1. Reset graphics settings to safe defaults
qbz --reset-graphics

# 2. Disable GPU hardware acceleration entirely
QBZ_HARDWARE_ACCEL=0 qbz

# 3. Force X11 instead of Wayland (common fix for NVIDIA)
QBZ_FORCE_X11=1 qbz

You can combine flags:

QBZ_HARDWARE_ACCEL=0 QBZ_FORCE_X11=1 qbz

Flatpak Graphics Issues

If running QBZ from Flathub:

QBZ_HARDWARE_ACCEL=0 flatpak run com.blitzfc.qbz

Application Issues

QBZ Won't Start / Crashes on Launch

1. Try resetting graphics settings:

   qbz --reset-graphics

2. Check logs for errors:

   # System journal
   journalctl --user -u qbz --since "5 minutes ago"
   
   # Or launch from terminal to see output
   qbz

3. If using Flatpak:

   flatpak run com.blitzfc.qbz --reset-graphics

Stuck on a Broken View

If QBZ opens to a broken or blank view, it may be due to a corrupted session state:

# For development builds
npm run -s dev:reset-last-view

# For installed versions, the session database is at:
# ~/.local/share/qbz/users/<user-id>/session.db
# Delete or rename it to reset the session state

Login Issues

• Verify your Qobuz credentials work on the Qobuz website
• Check your internet connection
• If you recently changed your Qobuz password, you may need to re-login in QBZ

Flatpak-Specific Issues

Audio Not Working in Flatpak

Ensure PipeWire permissions are granted:

# Check permissions
flatpak info --show-permissions com.blitzfc.qbz

# Reset permissions if needed
flatpak override --user --reset com.blitzfc.qbz

Can't Access Music Files in Flatpak

Flatpak sandboxes file access. Grant access to your music directories:

flatpak override --user --filesystem=/path/to/your/music com.blitzfc.qbz

Getting Help

If your issue isn't covered here:

1. Check the GitHub Issues for existing reports
2. Open a new issue with:
   • QBZ version (Settings > About)
   • Linux distribution and version
   • Audio backend and device
   • Steps to reproduce the issue
   • Any relevant log output