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

QBZ 2.0+ is a native Slint app and renders through one of three tiers — GPU (wgpu), GPU compatibility (OpenGL), or Software (CPU) — auto-selected for your hardware. Hardware acceleration is on by default. Most rendering problems are fixed by forcing a lower tier with the QBZ_RENDERER env var.

Black Screen, Crash on Launch, or Rendering Glitches

Quick fix — drop to the OpenGL compatibility tier:

QBZ_RENDERER=gl qbz

If that still fails — force pure software rendering:

QBZ_RENDERER=software qbz

Flatpak:

QBZ_RENDERER=software flatpak run com.blitzfc.qbz

You cannot get permanently stuck on a bad renderer: if a forced choice never reaches a usable state, QBZ auto-reverts to Auto on the next launch. Launch from a terminal to watch the tier decision ([renderer] ... lines).

App is Slow / Pegs the CPU (VMs)

In a VM without GPU passthrough, the GPU tier can bind a software Vulkan adapter and CPU-rasterize the whole UI. Force the lighter pure-software renderer:

QBZ_RENDERER=software qbz

Missing Dynamic Background or Shader Visualizers

The app-wide dynamic background and immersive shader scenes need the GPU (wgpu) tier. On the GL or Software tiers they're unavailable by design — the rest of the UI is fully functional.

For the full renderer model, the Settings controls (Rendering backend, Preferred GPU), the auto-degradation ladder, and every environment variable, see the dedicated Composition page.

Wayland vs X11

QBZ renders natively on both Wayland and X11 — there's no Force-X11 toggle anymore (that was a WebKit-era knob). If you hit a GPU-init issue on one session type, the QBZ_RENDERER=gl / software fallbacks above are the fix, independent of the display server.

Application Issues

QBZ Won't Start / Crashes on Launch

1. If it's GPU-related, force a lower renderer tier (see Graphics Issues above):

   QBZ_RENDERER=gl qbz        # or QBZ_RENDERER=software qbz

2. Check logs for errors — just launch from a terminal to see startup output, including the renderer decision:

   qbz

3. A forced renderer that fails auto-reverts to Auto on the next launch, so a plain relaunch often clears a GPU-init crash on its own.

Stuck on a Broken or Blank View

If QBZ opens to a broken or blank view, it may be corrupted UI/session state. The renderer choice and interface prefs live in a JSON file; per-user session state lives in a SQLite DB:

# Interface prefs (theme, renderer, last view, etc.):
# ~/.local/share/qbz/ui_prefs.json

# Per-user session database:
# ~/.local/share/qbz/users/<user-id>/session.db

Delete or rename the relevant file to reset that state, then relaunch. Resetting the renderer key in ui_prefs.json to "auto" reverts a bad renderer choice.

Single-Instance (Linux)

On Linux, QBZ is single-instance: launching a second copy raises the existing window (via a D-Bus Present() call) instead of opening a new one. Passing a Qobuz link to a second launch opens that link in the running instance. If a crashed instance leaves a stale lock and QBZ refuses to start, ensure no qbz process is still running (pgrep qbz) before relaunching.

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

Qobuz Server Errors (504 Gateway Timeout)

If tracks fail to play with server errors, QBZ automatically retries up to 4 times with increasing delays (1s, 2s, 4s) and falls back to lower quality.

Signs of Qobuz server issues:

• Orange warning triangle in the player bar (degraded indicator)
• "Streaming issue" dialog appearing
• Tracks that play fine at other times failing repeatedly

What you can do:

• Let QBZ handle it — the retry system resolves most transient issues
• Set "When quality retries fail" to "Always try lowest quality" in Settings > Audio to avoid the dialog
• Wait a few minutes — Qobuz server issues are usually temporary

Logs & Diagnostics

QBZ has a built-in log viewer and diagnostics report — you rarely need to hunt through files. Both are under Settings > Developer:

• Application logs opens the in-app log viewer over QBZ's live in-memory log ring. It has auto-tail, Copy all (copies a full, secret-redacted diagnostics bundle — system info plus the live log lines), and Upload, which posts that bundle to a public paste and gives you a shareable URL to drop into a bug report. Secrets and tokens are redacted before anything leaves your machine.
• Diagnostics is an inline panel (display server, GPU vendors, detected GPU name, desktop environment, VM status, the active renderer tier and why it was chosen, and more). Export to clipboard copies the whole report.

When filing a bug, the uploaded log URL or the exported diagnostics is the single most useful thing to attach.

Headless Daemon (qbzd)

If your trouble is with the headless daemon on a streaming box rather than the desktop app, its diagnostics live in the CLI, not this page. Start with:

qbzd status     # names the failing subsystem (auth, audio, playback, Connect, network)

Full daemon troubleshooting — silent output, the box vanishing from the Qobuz app (linger), DAC not detected, identity collisions after a settings import — is on the Headless Daemon manual and the worked Build a Streaming Box guide.

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
   • The uploaded log URL or exported diagnostics (Settings > Developer)