feat(docs): add troubleshooting page

docs/.vitepress/config.mts

@@ -2,7 +2,7 @@ import { defineConfig } from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  title: "Koel",
+  title: "koel",
   description: "The official documentation for Koel, the music streaming solution that works",
   head: [
     [
@@ -91,7 +91,11 @@ export default defineConfig({
       {
         text: 'Local Development',
         link: '/development'
-      }
+      },
+      {
+        text: 'Troubleshooting',
+        link: '/troubleshooting'
+      },
     ],
 
     socialLinks: [

docs/troubleshooting.md

@@ -0,0 +1,82 @@
+---
+outline: [2, 2]
+---
+
+# Troubleshooting
+
+While Koel strives to be as user-friendly and bug-free as possible, things can still go wrong.
+Don't panic! This page will guide you through the process of troubleshooting your issues.
+
+## First Steps
+
+When a wild error appears, the very first step you should take is to check `storage/logs/laravel.log`.
+More often than not, this file will provide you with a lot of details and hints on what went wrong.
+This is so important that it is worth repeating:
+
+:::danger Always check the log
+If you receive an error, the first step is to take a look at `storage/logs/laravel.log`.
+:::
+
+Next, look at the browser console for any JavaScript errors.
+While you're at it, check the network tab for any failed requests and try disabling the network cache.
+
+Also, try clearing the cache and recompiling the front-end assets. Below are a couple of commands that might help in this area:
+
+```bash
+# Clear node_modules, re-install, and re-build the front-end assets
+rm -rf node_modules && yarn install && yarn build
+
+# Clear the Laravel cache
+php artisan cache:clear
+
+# Clear the Laravel config cache
+php artisan config:clear
+```
+
+If you're still stuck, check below for a couple of common issues and their solutions.
+
+## Common Issues
+
+### You receive a `Class 'Pusher' not found` error
+
+Solution: Add or set `BROADCAST_DRIVER=log` in your `.env` file. This will instruct Laravel to use `log` as the default broadcast driver instead.
+
+### You receive an "Unknown error" when scanning using the web interface
+
+Solution: Try scanning from the command line with php artisan koel:sync. Most of the time, you should receive a more detailed, easier to debug, message.
+Refer to [Music Discovery](usage/music-discovery) for more details.
+
+### You receive an `Integrity constraint violation: 1062 Duplicate entry for key 'artists_name_unique'` error when scanning
+
+Solution: Set your database and table collation to utf8_unicode_ci.
+
+### You receive an <input random strings here> error when running `yarn`
+
+Solution: This most likely has little to do with Koel but more with your node/npm/yarn environment and installation. Deleting `node_modules` and rerunning the command sometimes help.
+
+### Song stops playing, and you receive a `Failed to load resource: net::ERR_CONTENT_LENGTH_MISMATCH` error
+
+Solution: This may sometimes happen with the native php streaming method. Check [Streaming Music](usage/streaming) for alternatives.
+
+### Next song doesn't play if your mobile device is locked
+
+Solution: This is a limitation for mobile browsers, at least for iOS.
+There's no known solution at the moment, but you can try using the [mobile app](mobile-apps) instead.
+
+## Reinstalling Koel
+
+In the worst case scenario, you can always reinstall Koel. Although Koel doesn't provide a built-in way to reinstall itself, you can do so manually by following these steps:
+
+1. Backup your database
+2. Have you backed up your database yet?
+3. No seriously, make sure you have a backup of your database
+4. Back up the `public/img` directory. This is where your album art, artist images, user avatars etc. are stored.
+5. Delete or empty the root Koel directory
+6. Follow the [installation guide](guide/getting-started#installation) to install Koel afresh
+7. Restore your database and the `public/img` directory
+
+By now you should have a fresh Koel installation with all your data intact and hopefully without the issue you were facing.
+
+## Ask for Help
+
+If you're still stuck, the [issue page](https://github.com/koel/koel/issues) on GitHub is a good place to ask for help. Remember to be civil and patient.