koel/docs/troubleshooting.md

---
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.