Troubleshooting

Running into issues? Here are solutions to the most common problems.

Installation Issues

"Composer koel:init" fails

• Ensure PHP 8.2+ is installed: php -v
• Check required extensions: php -m | grep -E 'exif|gd|fileinfo'
• Verify database credentials in .env

"SQLSTATE" database errors

• For SQLite: ensure the database file path is absolute in .env
• For MySQL/PostgreSQL: verify the server is running and credentials are correct
• Run php artisan migrate to ensure all tables are created

Playback Issues

Songs won't play

1. Check browser console for errors (F12 > Console)
2. Verify the media path is correct in Settings
3. Ensure PHP has read access to your music files
4. Try switching streaming methods in Settings

Audio cuts out or stutters

• Switch from PHP to x-accel-redirect or mod_xsendfile
• Check server memory and CPU during playback
• If transcoding, ensure FFmpeg is properly installed: ffmpeg -version

Library Issues

Songs not appearing after scan

• Verify files have valid audio metadata (ID3 tags)
• Check file permissions: PHP user must be able to read the files
• Run verbose scan: php artisan koel:scan --verbose
• Supported formats: MP3, AAC, OGG, FLAC, WAV

Album art not showing

• Embed album art directly in audio files (recommended)
• Koel also looks for cover.jpg or folder.jpg in album directories

Server Issues

Koel is slow

• Enable caching: php artisan config:cache && php artisan route:cache
• Use a production web server (Nginx/Apache) instead of php artisan serve
• Check database query performance

Health Check

Run the built-in doctor:

php artisan koel:doctor

This diagnoses common configuration issues automatically.

Still stuck?

Visit the Koel community for help, or check the official documentation.