Troubleshooting

Troubleshooting

Spotify and hosted display

Symptom	What to check
Spotify rejects the callback	Register the exact HTTPS callback, match redirectUri in config.json, and retain /spotify/ with its trailing slash.
Provider configuration is unavailable	Serve the exact two-field config.json as JSON, disable caching for it, and remove extra fields.
Spotify access was revoked	Open ?setup=1, disconnect, then connect and approve Spotify again.
Nothing is playing	Start a Spotify track or episode. Phrasic displays metadata; it does not play audio.
The current item is unsupported	The Spotify provider currently displays tracks and podcast episodes.
A width diagnostic appears	Supply one integer width from 320 through 7680; use setup=1 only when controls are needed.
The Fake Music route returns 404	This is the production default. Set FAKE_PROVIDER_ENABLED=true only for a deliberate test deployment.

Local playback

Symptom	What to check
Local playback is unavailable	Confirm the native process and target-matching Local host are running, then restart phrasic serve to create a fresh pairing.
The pairing URL no longer works	Pairing capabilities are one-use and process-lifetime. Restart the service and use the new URL.
The wrong browser opens	Set browser_handoff = "print" and open the printed URL in the intended browser or browser-source surface.
Playback does not change promptly	Confirm the native source reports current playback signals. Phrasic also polls and retries automatically when a signal is missed.
No artwork appears on Linux	The selected source must provide a readable file:// image or a public HTTPS PNG, JPEG, or WebP within the source deadline. Metadata remains available when artwork fails.
Pausing clears the previous item	This is intentional. Paused and stopped playback return to the neutral spinning vinyl.
A pinned source disappears	An exact source_pin fails closed and does not silently select another source.

For configuration and lifecycle details, see Local playback.