🔧 Troubleshooting

Common issues and solutions for nJukebox problems

Quick Diagnostics

Start with this checklist to identify common issues:

System Status Check

Common Issues

🚫 Cannot Start nJukebox Server

Symptoms: Error messages when running startup scripts, server won't start

Causes & Solutions:

  • Port already in use: Another application is using port 5500 or 3001 
    # Find what's using the ports
netstat -ano | findstr :5500
netstat -ano | findstr :3001
# Kill the process using task manager or change the ports in config.json
  • Binary not built: The Go binary has not been compiled yet 
    # Build the binary (Go is only needed to build)
go build -o njukebox ./cmd/njukebox
  • Permission issues: Script can't access files/directories 
    # Run as administrator or check file permissions

🎵 No Music Shows in Library

Symptoms: Library is empty, no tracks visible, "No tracks found" message

Causes & Solutions:

  • Empty music directory: No MP3 files in /music folder
    • Add MP3 files to the music directory
    • Supported formats: MP3, FLAC, M4A, OGG
  • Database not scanned: Music database needs to be built
    • Use Admin Panel → Settings → "Rescan Music"
    • Wait for scan to complete (check console output)
  • Database corruption: Music database is corrupted
    • Delete data/music.db
    • Restart server and rescan music
  • File permissions: Server can't read music files
    • Check folder permissions
    • Ensure server has read access to music directory

🔇 No Audio Playback

Symptoms: Music appears to play but no sound, audio controls don't work

Causes & Solutions:

  • Browser autoplay policy: Browser blocks autoplay
    • Click anywhere on the page to enable audio
    • Allow autoplay for 127.0.0.1 in browser settings
  • Audio codec issues: Browser can't decode audio format
    • Test with different MP3 files
    • Convert problematic files to standard MP3
  • CORS issues: Cross-origin restrictions blocking audio
    • Ensure accessing via 127.0.0.1:5500, not file://
    • Check console for CORS errors
  • System audio: Computer audio is muted or low
    • Check system volume
    • Test audio with other applications

🔐 Cannot Access Admin Panel

Symptoms: Admin PIN doesn't work, lock icon doesn't respond

Causes & Solutions:

  • Wrong PIN: Using incorrect admin PIN
    • Default PIN is 1234
    • The PIN is stored in the settings database and can be changed in the Admin Panel
  • JavaScript errors: Browser errors preventing admin panel
    • Open browser developer tools (F12)
    • Check Console tab for errors
    • Reload page and try again
  • Session timeout: Admin session has expired
    • Refresh page and log in again
    • Increase sessionTimeout in config.json

🎤 Spotify Connection Issues

Symptoms: Cannot connect to Spotify, authentication fails

Causes & Solutions:

  • Invalid Client ID: Spotify credentials not configured
    • Check Spotify Developer Dashboard
    • Verify Client ID in config.json
    • Ensure redirect URI matches exactly
  • Spotify Premium required: Free accounts can't use Web Playback API
    • Upgrade to Spotify Premium
    • Use local music only if needed
  • Network connectivity: Cannot reach Spotify servers
    • Check internet connection
    • Verify firewall allows outbound HTTPS

Performance Issues

⏳ Slow Library Loading

Solutions:

  • Large music libraries take time to scan initially
  • Subsequent loads use cached data and are faster
  • Consider organizing music into smaller subdirectories
  • Disable auto-scan for very large libraries

💾 High Memory Usage

Solutions:

  • Restart nJukebox server periodically
  • Clear cover cache from admin panel
  • Reduce library scan interval
  • Limit playlist size in config.json

Browser-Specific Issues

Chrome/Edge Issues

  • Autoplay: May require user interaction before audio plays
  • File limits: Very large libraries may hit memory limits
  • CORS: Strict cross-origin policies

Firefox Issues

  • Audio formats: Limited codec support compared to Chrome
  • Performance: May be slower with large visualizations
  • Extensions: Ad blockers may interfere

Safari Issues

  • Limited support: Some features may not work properly
  • Audio codecs: Strict format requirements
  • Web technologies: May not support latest web APIs

Network Issues

🌐 Cannot Access from Other Devices

Solutions:

  1. Change host from "127.0.0.1" to "0.0.0.0" in config.json
  2. Configure Windows Firewall to allow ports 5500 and 3001
  3. Find your computer's IP address: ipconfig
  4. Access from other devices using: http://YOUR_IP:5500

🚪 Firewall Blocking Connection

Windows Firewall Configuration:

  1. Open Windows Defender Firewall
  2. Click "Allow an app or feature through Windows Defender Firewall"
  3. Click "Change Settings" then "Allow another app..."
  4. Browse to the njukebox binary or add ports 5500 and 3001
  5. Enable for both Private and Public networks

Database Issues

🗄️ Database Corruption

Symptoms: Server crashes, data loss, SQLite errors

Recovery Steps:

  1. Stop nJukebox server
  2. Backup current database files
  3. Delete corrupted .db files from /data directory
  4. Restart server (creates new databases)
  5. Rescan music library from admin panel
  6. Reconfigure settings as needed

Error Messages

"bind: address already in use"

Port 5500 or 3001 is being used by another application. Either close the other application or change the ports in config.json.

"go: command not found"

Go is not installed or not in PATH. Go is only needed to build the binary — a prebuilt binary runs without it.

"SQLITE_CORRUPT: database disk image is malformed"

Database is corrupted. Delete the .db files and restart to rebuild the database.

"Failed to load resource: net::ERR_CONNECTION_REFUSED"

Cannot connect to the server. Ensure nJukebox server is running and accessible.

Log Analysis

Enabling Debug Mode

Enable detailed logging to diagnose issues:

  1. Enable the debug toggle in the Admin Panel settings
  2. Open browser developer tools (F12)
  3. Check Console tab for detailed messages
  4. Monitor server terminal for backend logs

Common Log Messages

  • "Music scan completed": Library scan finished successfully
  • "Spotify token refreshed": Spotify authentication working
  • "Database error": Database connection or query failed
  • "CORS error": Cross-origin request blocked
  • "Audio context suspended": Browser autoplay restriction

Getting Help

Information to Gather

When seeking help, collect this information:

  • Operating system and version
  • Go version (only when building from source)
  • Browser and version
  • nJukebox version/commit
  • Complete error messages
  • Console logs (browser F12)
  • Server terminal output
  • Configuration files (remove sensitive data)

Safe Mode Testing

Test with minimal configuration:

  1. Use default config.json settings
  2. Test with a small number of MP3 files
  3. Disable Spotify integration
  4. Test in Chrome with no extensions
  5. Access only via 127.0.0.1:5500
Still Need Help? If issues persist after trying these solutions, gather the diagnostic information above and consult the project documentation or community support resources.

Preventive Maintenance

Regular Tasks

  • Weekly: Clear cover cache if using many tracks
  • Monthly: Backup database files
  • After updates: Test all functionality
  • Before events: Full system test and backup

System Health Monitoring

  • Monitor disk space (covers and cache can grow)
  • Check memory usage during long sessions
  • Verify network connectivity for Spotify features
  • Test admin access periodically