Troubleshooting

Something is not working. Find your symptom in the table below and follow the link — each entry goes directly to the relevant fix, not a general overview.

🔗Find your symptom

🔗Run a quick self-check first

Before digging into a specific page, run the built-in diagnostic command. It checks the render loop, device output queues, and config in about one second:

hypercolor diagnose

Or call the endpoint directly if the CLI is not in scope:

curl -s -X POST http://localhost:9420/api/v1/diagnose | jq '.data.summary'

The response includes a summary with passed, warnings, and failed counts and a checks array with per-subsystem detail. A warning on render_loop or output_queues tells you which page to read next.

Target specific check categories to narrow the output:

# Check only device output state
hypercolor diagnose --check devices

# Check render pipeline only
hypercolor diagnose --check render

# Full report to file — attach to bug reports
hypercolor diagnose --report ~/hypercolor-diag.json --system

🔗Check the logs

When a diagnostic check fails and you need more context, structured logs are the fastest path to the root cause. The daemon uses tracing throughout; set RUST_LOG before starting it:

# Recommended starting point for most issues
RUST_LOG=debug just daemon

# USB device problems
RUST_LOG=hypercolor_hal=debug just daemon

# Render pipeline and FPS issues
RUST_LOG=hypercolor_core::engine=trace just daemon

# Audio input
RUST_LOG=hypercolor_core::input=debug just daemon

The daemon defaults to info level, which is quiet by design. debug gives you device connections, protocol steps, and effect changes without flooding the terminal. trace on a specific module is only needed when a subsystem is actively misbehaving.

🔗Troubleshooting pages

🔗Devices not found

USB devices that are visible in lsusb but do not appear in Hypercolor, permission failures, conflicting software holding the HID device, and firmware-split or rebrand quirks for Lian Li and PrismRGB hardware.

🔗Audio not reacting

Audio-reactive effects that stay static: selecting the right PipeWire or PulseAudio monitor source, verifying the audio capture pipeline, and fixing the most common configuration mistakes.

🔗Network discovery

WLED, Philips Hue, Nanoleaf, and Govee devices that do not appear in discovery. Covers mDNS requirements, per-protocol pairing flows (Govee LAN control toggle, Hue link-button timing, Nanoleaf power-button hold), VLAN and AP-isolation issues, and firewall rules.

🔗Studio

Spatial layout problems (all LEDs showing the same color), zone configuration issues, scene activation not behaving as expected, and layer ordering surprises.

🔗Common issues

Linux-specific first-run failures that are not hardware or audio related: daemon port conflicts, systemd user session constraints, XDG_RUNTIME_DIR not available on headless systems, and the WebSocket preview channel not connecting.

🔗Performance

Low FPS, render loop budget misses, device output lag, GPU sampling fallbacks, and Servo circuit breaker trips. Includes how to read the performance snapshot from hypercolor diagnose and how to enable per-phase timing traces.

🔗Still stuck?

If none of the above pages resolve your issue:

1. Run hypercolor diagnose --report ~/hypercolor-diag.json --system to capture a full diagnostic snapshot.
2. Check RUST_LOG=debug daemon output for the first ERROR or WARN line that appears when the problem occurs.
3. Open an issue on GitHub and attach the report file.

For developer-level log analysis, internal bus tracing, and WebSocket stream inspection, see Debugging in the contributing section.