Troubleshooting

The failures worth documenting are the silent ones — the app starts, looks right, and does nothing useful. Here they are, symptom first.

Symptom → cause

Symptom	Cause & fix
Pages render with no styling	`npm run build` wasn't run — check `public/build/manifest.json` exists
Avatars and artist images 404, everything else works	`php artisan storage:link` was skipped or failed. On Windows, symlinks need Developer Mode or an Administrator terminal.
Scan finds nothing	Watch-folder paths: absolute, comma-separated, readable by the PHP process. On Windows this is the most likely failure — see Install on Windows, step 7.
Files catalogue but won't play	`ffmpeg` isn't on the PATH. `ffmpeg -version` in the same shell that runs the server.
Metadata never fills in / downloads never start / a transfer sits idle	`php artisan queue:work` isn't running — see Background workers
Phones can't find the server	`APP_URL` missing its port, or the firewall. Confirm another device on the LAN can open `http://<server-ip>:8000/app` first.
`cURL error 60` on everything outbound	Windows PHP has no certificate bundle — Install on Windows, step 4
Services page says unsupported	Expected off macOS — it's launchd-based. Run the workers natively instead.
Locked out of your account	`php artisan user:password you@example.com` at the server console — self-hosted installs have no reset email.

The tools you already have

Admin → Device reports — every device reports its failures back to the server, filterable by device and log type. When "the phone doesn't work" and the phone isn't in the room, start here.
The test suite — php artisan test on the server. If it fails, the problem is the PHP or Node install, not your library.
The log — metadata sources that skip themselves (no key, no answer) say so in the log rather than failing silently.

Still stuck?

Open an issue on GitHub with the symptom, your OS, and anything Device reports shows. Silent failures that make it into this table started as somebody's bug report.