Skip to content

Troubleshooting

Installation troubleshooting

Plugin Not Appearing After Installation

Check Installation Status:

  1. Go to Dashboard → Plugins
  2. Verify Jellyfin Enhanced is listed under Installed
  3. Check that it's enabled (not disabled)

Run Startup Task:

  1. Go to Dashboard → Scheduled Tasks
  2. Find "Jellyfin Enhanced Startup" task
  3. Click Run to execute it manually
  4. Refresh your browser (Ctrl+F5)

Clear Browser Cache:

  1. Press Ctrl+Shift+Delete (Windows/Linux) or Cmd+Shift+Delete (Mac)
  2. Select "Cached images and files"
  3. Clear cache
  4. Refresh the page

Restart Server:

  1. In Jellyfin, go to: Dashboard → Restart
  2. Wait for server to fully restart
  3. Refresh browser

Permission Errors in Logs

If you see errors like:

Access to the path '/jellyfin/jellyfin-web/index.html' is denied.

Solution: - Install file-transformation plugin (recommended) - Or, try platform-specific permission fixes

Scripts Not Loading

Check Scheduled Task:

  1. Dashboard → Scheduled Tasks
  2. Look for "Jellyfin Enhanced Startup"
  3. Verify it has a trigger for "On application startup"
  4. If missing, add the trigger manually

Check Browser Console:

  1. Press F12 to open developer tools
  2. Go to Console tab
  3. Look for errors mentioning "Jellyfin Enhanced"
  4. Report errors on GitHub if found

Update Not Working

Clean Update Process:

  1. Go to Dashboard → Plugins → My Plugins
  2. Find Jellyfin Enhanced
  3. Click Uninstall
  4. Restart server
  5. Reinstall from Catalog
  6. Restart server again
  7. Clear browser cache (Ctrl+F5)

Verification Checklist

After installation, verify these work:

  • [ ] Plugin menu item appears in sidebar
  • [ ] Pressing ? opens the settings panel
  • [ ] Keyboard shortcuts work
  • [ ] Tags appear on media posters (if enabled)
  • [ ] No errors in browser console (F12)
  • [ ] No errors in server logs

Platform-Specific Issues

Docker

If you are not using file-transformation and see permission errors like:

System.UnauthorizedAccessException: Access to the path '/jellyfin/jellyfin-web/index.html' is denied.

You'll need to manually map the index.html file:

  1. Copy the index.html file from your container:
docker cp jellyfin:/jellyfin/jellyfin-web/index.html /path/to/your/jellyfin/config/index.html
  1. Add volume mapping to your Docker run command:
-v /path/to/your/jellyfin/config/index.html:/jellyfin/jellyfin-web/index.html
  1. Or for Docker Compose, add to volumes section:
services:
  jellyfin:
    volumes:
      - /path/to/your/jellyfin/config:/config
      - /path/to/your/jellyfin/config/index.html:/jellyfin/jellyfin-web/index.html

Warning

This method is not recommended and won't survive a jellyfin-web upgrade. The recommended method for Docker:

  1. Install the File Transformation plugin
  2. Follow the standard installation process

Windows

If you see permission denied errors:

  1. Navigate to your Jellyfin installation folder (usually C:\Program Files\Jellyfin\Server)
  2. Right-click the folder → Properties → Security
  3. Grant "NETWORK SERVICE" Read and Write permissions
  4. Apply to all subfolders and files
  5. Restart Jellyfin service

Linux

If you encounter permission issues, this is a known solution

Bash:

sudo chown -R jellyfin:jellyfin /usr/lib/jellyfin/
sudo chmod -R 755 /usr/lib/jellyfin/

Getting Help

If you encounter issues:

  1. Check the FAQ for common solutions
  2. GitHub Issues
    • Search existing issues
    • Create a new issue (please include log and details)
  3. Join the Discord Community