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, reinstalling dependencies, and recompiling the front-end assets. Below are a couple of commands that might help in this area:

# Remove Composer vendor/ directory and reinstall the packages
rm -rf vendor && composer install

# 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 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 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 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 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 on GitHub is a good place to ask for help. Remember to be civil and patient.