Troubleshooting

Luuster cannot reach the server

Check the following:

1. Open the Music Assistant server URL from the same device and network.
2. Include http:// or https:// in the URL.
3. Include a non-standard port when your setup requires one.
4. Confirm that a reverse proxy forwards WebSocket connections as well as normal HTTP traffic.
5. Check whether a VPN, firewall, or local network policy blocks the device.

Login succeeds but the app is empty

The initial state synchronization may have failed or a provider response may contain data Luuster does not yet handle correctly.

Record:

• the Music Assistant server version;
• the affected screen;
• whether players appear;
• whether restarting Luuster changes the result;
• relevant application logs with secrets removed.

Playback state looks stale

Luuster relies on server events to stay synchronized. Verify that:

• the server remains connected;
• WebSocket traffic reaches the client;
• the same player is selected in Luuster and the other control surface;
• the player itself is still available in Music Assistant.

Do not publish secrets

Remove access tokens, passwords, private hostnames, public IP addresses, and personal media metadata before attaching logs to a public issue.