View source for JELLYFIN - Debug Mode And Troubleshooting

[[Category:Wiki]]

=== Enabling Debug Mode ===

To enable debug mode in Jellyfin, you need to modify the configuration file or start the server with a specific environment variable. Debug mode provides additional logging and information that can help in diagnosing issues.

==== Modifying the Configuration File ====

To modify the configuration file:

* Navigate to the Jellyfin configuration directory. The path will vary depending on your operating system:
  * Linux: `/etc/jellyfin/`
  * Windows: `C:\ProgramData\Jellyfin\Server\config\`
  * macOS: `/usr/local/var/jellyfin/`

* Locate the `jellyfin.conf` or `config.json` file. Open it in a text editor.

* Add or modify the following setting under the `logging` section:
  
  <pre>
  {
      "LogLevel": "Debug"
  }
  </pre>

* Save the file and restart the Jellyfin server for the changes to take effect.

==== Using Environment Variables ====

Alternatively, you can set the environment variable directly when starting Jellyfin. For example, on Linux or macOS:

 <nowiki>
export JELLYFIN_LOG_LEVEL=debug</nowiki>

On Windows:

 <nowiki>
set JELLYFIN_LOG_LEVEL=debug</nowiki>

After setting this environment variable, restart Jellyfin to begin logging in debug mode.

=== Accessing Logs ===

Once debug mode is enabled, Jellyfin will generate detailed logs that can be accessed for troubleshooting.

==== Default Log Locations ====

* Linux: `/var/log/jellyfin/`
* Windows: `C:\ProgramData\Jellyfin\Server\logs\`
* macOS: `/usr/local/var/log/jellyfin/`

The log files include information about server activity, plugin operations, errors, and detailed debug messages. Common log files include:
* `jellyfin.log`: General server logs.
* `ffmpeg.log`: Logs related to media transcoding.
* `metadata_*.log`: Logs related to metadata processing.

==== Viewing Logs ====

You can use any text editor or command-line tools to view the logs. For example, on Linux or macOS:

 <nowiki>
cat /var/log/jellyfin/jellyfin.log</nowiki>

For real-time viewing, use:

 <nowiki>
tail -f /var/log/jellyfin/jellyfin.log</nowiki>

On Windows, open the `.log` files with any text editor like Notepad.

=== Troubleshooting Jellyfin ===

The troubleshooting chapter focuses on resolving common issues using the information from debug logs and additional configuration tips.

==== Server Not Starting ====

If Jellyfin does not start, check the following:

* Verify that the logs show any errors at startup. Common messages may include missing files, permission issues, or failed database migrations.

* Check that the Jellyfin service is running (on Linux or macOS):

 <nowiki>
systemctl status jellyfin</nowiki>

If it's not running, start it using:

 <nowiki>
systemctl start jellyfin</nowiki>

On Windows, check the Windows Services panel for the Jellyfin service.

* Check for database corruption. If the database is corrupted, Jellyfin may fail to start. You can try deleting the `metadata` folder (after backing it up) to force Jellyfin to rebuild the metadata and database:

 <nowiki>
rm -rf /var/lib/jellyfin/metadata/</nowiki>

On Windows:

 <nowiki>
rd /s /q "C:\ProgramData\Jellyfin\Server\metadata"</nowiki>

==== Playback Issues ====

If you're experiencing playback issues such as buffering or failure to start media, follow these steps:

* **Check Transcoding Logs**: Review the `ffmpeg.log` file to determine if there were any issues with the transcoding process. Look for errors such as missing codecs, failed transcoding, or unsupported formats.

* **Transcoder Settings**: You may need to adjust the transcoder settings. In the Jellyfin dashboard, go to **Admin > Playback** and review the settings for hardware acceleration and transcoding.

* **Test Direct Playback**: If possible, try direct playback of the media (without transcoding) to see if the issue is related to transcoding. You can disable transcoding temporarily via the dashboard.

* **Network Issues**: Ensure there are no network issues that could be causing buffering. Check for network latency or bandwidth issues, especially if streaming media over the internet.

==== Metadata and Library Issues ====

If your metadata is not showing correctly or libraries are not updating:

* **Rescan Metadata**: Trigger a manual metadata refresh. This can be done through the dashboard by navigating to **Admin > Libraries**, selecting your library, and choosing "Scan Library Files".

* **Permissions Issues**: Ensure that Jellyfin has proper permissions to read and write to the directories containing your media files.

* **Force Rebuild Database**: If metadata issues persist, you may need to force a full library rebuild. This can be done by deleting the metadata folder (as described earlier) and rescanning.

==== Plugin Issues ====

If Jellyfin plugins are not functioning correctly:

* **Check Plugin Logs**: Review the logs for specific plugin errors. Plugins often generate their own log files within the Jellyfin logs directory.

* **Reinstall Plugins**: Try disabling and re-enabling the plugin through the Jellyfin dashboard. If problems persist, try uninstalling and reinstalling the plugin.

* **Plugin Compatibility**: Make sure the plugins you are using are compatible with your version of Jellyfin. Some plugins may require updates after a Jellyfin upgrade.

=== Useful Links ===

* [Official Jellyfin Documentation](https://jellyfin.org/docs/)
* [Jellyfin GitHub Repository](https://github.com/jellyfin/jellyfin)
* [Jellyfin Community Forum](https://forum.jellyfin.org/)
* [Jellyfin Troubleshooting Guide](https://jellyfin.org/docs/general/troubleshooting/)
* [Jellyfin Discord Server](https://discord.gg/jellyfin)
* [Jellyfin Subreddit](https://www.reddit.com/r/jellyfin/)
* [Jellyfin Debugging and Logs Wiki](https://github.com/jellyfin/jellyfin/wiki/Debugging)