Troubleshooting

Troubleshooting

Start with Settings → Diagnostics, which reports Orchard's version, platform, native addon status, service reachability, and recent errors. Attach it to any support report.

Playback

Nothing plays at all

1. Check Diagnostics for a service reachability failure.
2. Sign out and back in. Session cookies expire, and a stale session fails at stream resolution rather than at browse.
3. Confirm the correct output device in Settings → Audio Engine → Output device. A device that has since been unplugged still shows as selected.

Age-restricted tracks fail while everything else works

Age-gated playback requires a signed-in session. Sign in and retry. If it still fails after signing in, this is usually an upstream change in how YouTube gates that content rather than a local problem; file an issue with the Diagnostics output.

One specific track fails, others are fine

Orchard has several recovery paths (re-resolution on expired URLs, authenticated retry, music-video fallback). If they all fail, the track is likely unavailable for your account or region. Try it on YouTube Music's website with the same account to confirm.

Playback stutters or the crossfade never engages

Smart Crossfade needs both tracks decodable up to 30 seconds before the transition. On a slow connection, preparation may not finish in time and Orchard falls back to a normal fade. Enabling and enlarging the Song Cache helps significantly.

Audio is quiet, distorted, or clipping

If you have boosted equalizer bands, pull Preamp down in Settings → Audio Engine. Boosting ten bands by +6 dB without preamp compensation clips.

Smart Crossfade

Transitions sound like plain fades

Smart Crossfade grades each transition and degrades on purpose. Common reasons:

Reason	Meaning	What helps
beat-confidence	The analyzer is not sure enough about the beat grid	Let analysis finish; some material genuinely has no stable grid
tempo-distance	The stretch needed exceeds 4%	Nothing; stretching further would be audible
outgoing-tempo / incoming-tempo	Detected tempo outside 40 to 220 BPM	Nothing; the tempo reading is being treated as noise

Spoken word, ambient, live recordings, and heavily rubato material will rarely beat-match, which is the correct outcome.

Transitions never happen on album playback

Consecutive tracks from the same album are detected and deliberately not crossfaded, so albums meant to run continuously do.

A transition clips at the start

If scheduling ends up more than 350 ms late relative to the planned downbeat, Orchard falls back rather than clipping. Persistent lateness usually means system audio stalls or heavy CPU contention.

Full detail in Smart Crossfade.

Sign-in

Sign-in window opens and immediately closes

Usually a leftover session in a bad state. Sign out fully, then sign in again.

Account switching loses the previous account

Cached sessions live in Orchard's per-user data directory. If that directory was cleared or is not writable, cached sign-in restore cannot work.

Recommendations have gone stale

Check Settings → Integrations → Send listening history to YouTube. With it off, your YouTube account never learns what you played, so recommendations stop moving.

Orchard Connect

Symptom	Likely cause
Phone cannot find the desktop	Different subnets, or guest Wi-Fi client isolation
Connection refused	Firewall blocking inbound TCP 32145
Pairing code rejected	Code expired; regenerate it from the desktop
Paired but keeps dropping	Desktop sleeping, or the LAN address changed via DHCP

Approval always happens on the desktop. If no request appears there, the phone never reached the server, which points at the network rather than at pairing.

More in Orchard Connect.

Listening parties

• Everyone plays locally, so a guest needs their own working playback.
• A track playable for the host may be unavailable for a guest by region or account.
• A guest without a signed-in session cannot play age-restricted tracks the host can.
• Closing the host's Orchard ends the room unless the host transferred the role first.

Integrations

Discord Rich Presence does not appear

Discord must be running locally with its IPC socket reachable. Under Flatpak, allow access to $XDG_RUNTIME_DIR/discord-ipc-0. Confirm the toggle in Settings → Integrations.

Last.fm scrobbles stop

Scrobbling depends on Orchard's Last.fm worker being reachable, since it owns the signing credentials. Check Diagnostics for service reachability, then reauthorize from Settings → Last.fm.

Lyrics missing or unsynced

Orchard reports which provider answered. Missing lyrics means no provider in the chain had them; unsynced means a provider had text but no timing.

Appearance and performance

High GPU or battery usage on a laptop

Set Settings → Appearance → Graphics mode to Integrated GPU and restart Orchard. This option is Windows and macOS only.

Backgrounds stutter

Lower Background intensity to Subtle, or switch Background motion to Artwork warp. Turning immersive backgrounds off entirely removes the cost.

Platform-specific

Windows SmartScreen blocks the installer

Builds are unsigned. Verify the checksum, then choose More info → Run anyway. See Installation.

macOS refuses to open the app

Builds are unsigned and unnotarized. Right-click and choose Open, or clear quarantine:

xattr -dr com.apple.quarantine /Applications/Orchard.app

Linux tray icon missing

Tray support needs a StatusNotifier host in your desktop environment. Some Wayland setups need an extension (for example, AppIndicator support on GNOME).

Media keys do nothing on Linux

Orchard disables Chromium's HardwareMediaKeyHandling on Linux and handles keys itself. If your desktop environment has already bound those keys to another player, it wins.

Data and recovery

Reset settings without losing everything

Export from Settings → Backup first, then clear the application data directory. Restore brings back preferences, queue state, audio profiles, Replay events, and pins.

Where the data lives

Platform	Path
Windows	%APPDATA%\Orchard
macOS	~/Library/Application Support/Orchard
Linux	~/.config/Orchard

Still stuck

• Public reports: Issues
• Private reports with diagnostics and screenshots: Orchard's in-app Support System, which creates a conversation you can follow inside the app

Include your Orchard version, platform, and Diagnostics output. It is the difference between a fix and a guess.