Troubleshooting

Eight common failures: what you see, why, and what to do. In the examples, the screen's address is 192.168.1.50.

“Aucun jeton” (No token)

What you see: The music card shows “aucun jeton” (no token) rather than a track.
The cause: MUSIC_ASSISTANT_JETON is empty: since 2.10, Music Assistant refuses any anonymous access.
The fix: Get a token and put it in /etc/ecran-atelier.env: Installing the screen chapter, step 5.

What you see: ecran-agent's log keeps repeating no route to host, even though the screen answers from a terminal.
The cause: macOS hasn't granted ecran-agent local network access yet: it's launched by launchd, without your Terminal's permissions.
The fix: Check the screen from a terminal (nc -vz 192.168.1.50 8098): if it answers, allow ecran-agent in System Settings → Privacy & Security → Local Network. Details: Installing the Mac service chapter, step 6.

What you see: ~/Library/Logs/ecran-agent.log stays empty, or stale: the LaunchAgent seems never to start, with no visible error message.
The cause: ecran-agent isn't signed with a Developer ID: if it still carries the quarantine flag, macOS refuses to launch it, with no dialog to click since launchd has no screen.
The fix: Remove the flag from the installed binary, not the downloaded file: xattr -d com.apple.quarantine ~/bin/ecran-agent, then restart the service. Details: Installing the Mac service chapter, step 3.

What you see: The track's progress bar runs ahead, behind, or jumps: it doesn't follow what you hear.
The cause: The screen works out this position from the moment Music Assistant recorded it: with a wrong clock, for lack of NTP synchronization, the calculation is wrong too.
The fix: Install systemd-timesyncd and check timedatectl: Installing the screen chapter, step 8.

What you see: Your machine's pill goes hollow, its keys go dark, and it says “injoignable depuis N min” (unreachable for N min) — or “jamais connectée” (never connected) if it has never shown up yet.
The cause: The TCP connection between ecran-agent and the screen is broken: Mac asleep, Wi-Fi lost, service stopped — or a token that no longer matches, in which case the pill says “refusée : jeton refusé” (refused: token refused).
The fix: Check that ecran-agent is running, and its log (Installing the Mac service chapter), and that its jeton matches, word for word, the one in JETONS_MACHINES on the screen. Music and the time carry on without interruption: only this machine's keys go silent.

What you see: “visualiseur absent de Music Assistant” (visualizer missing from Music Assistant), or “jeton refusé par le visualiseur” (token refused by the visualizer), in place of the spectrum: the rest of the music works.
The cause: The first message means Music Assistant's MilkDrop visualization relay isn't active; the second, that the token the screen presents to it is refused — the same family of failure as “aucun jeton” (no token).
The fix: Turn on the MilkDrop relay in Music Assistant; if it's the token, regenerate it as in the Installing the screen chapter.

What you see: A key shows with its label alone, no icon — the config isn't refused because of it.
The cause: icone's PNG path leads nowhere, or to a file your machine can't convert. This is only checked at startup and on every reread of config.json, not when it's read itself: the log then says <id> : pas d'icône, libellé seul (<id>: no icon, label only).
The fix: Check the path (absolute, see Creating your keys) and the file, or fall back to an emoji.

What you see: Nothing on the screen: your machine never shows up, not even “jamais connectée” (never connected). The only clue is in ~/Library/Logs/ecran-agent.log.
The cause: config.json is readable by someone other than you: like ssh, the service refuses to start before it even reads the screen or the token, so nothing goes out to the screen to say why.
The fix: chmod 600 ~/Library/Application\ Support/ecran-agent/config.json, then restart the service.