Quick answer

What this guide helps you do

Troubleshoot Jellyfin systematically. Fix missing media, scan failures, permissions, storage mounts, transcoding, subtitles, remote access and high CPU use.

Jellyfin beginner path

New to Jellyfin? Follow this order.

These guides form the SmallGrid Jellyfin path: install it, fix folder access, solve empty libraries, reduce unnecessary transcoding, then choose the right mini PC.

  1. Jellyfin on Ubuntu: Low-Power Setup, Media Folders and Reboot Checks
  2. Give Jellyfin Access to Media Folders on Ubuntu
  3. Jellyfin Library Not Showing Files? 8 Checks That Fix It
  4. Jellyfin Direct Play vs Transcoding: CPU, Quality and Compatibility
  5. Best Mini PC Specs for Jellyfin: What Actually Matters

Jellyfin problems are easier to fix when you identify which layer has failed before changing settings.

Most faults belong to one of these areas:

  1. storage is not mounted or available
  2. Jellyfin cannot access the folder
  3. the library points to the wrong path
  4. scanning is not detecting new media
  5. the client cannot play the original streams
  6. remote bandwidth or access is restricted
  7. hardware acceleration is configured incorrectly

This hub provides a practical decision tree and links to the detailed SmallGrid guides for each problem.

Start here: collect evidence

Before changing anything, record:

Jellyfin installation: native or Docker
Operating system:
Media path on host:
Media path inside container:
Storage type: internal, USB, network or pooled
Problem affects: all files, one library, one file or one client
Problem started after: reboot, update, move, permission change or unknown
Relevant Jellyfin log message:

For playback problems, also record:

Client:
Local or remote:
Direct Play, Direct Stream or Transcoding:
Video codec:
Audio codec:
Subtitle format:
Reported conversion reason:

Change one variable at a time and retest the same file or path.

Decision tree

Jellyfin cannot see any media

Check in this order:

  1. Does the file exist on the host?
  2. Is the storage mounted?
  3. Can the Jellyfin user traverse the directory path?
  4. Does the Docker container see the mapped folder?
  5. Does the Jellyfin library use the correct path?
  6. Does a manual scan produce an error?

Use:

Existing files appear but new files do not

Check:

  1. ownership and permissions of the new files
  2. automatic library monitoring
  3. scheduled scan tasks
  4. manual scan results
  5. storage availability
  6. naming and supported media types
  7. Jellyfin logs

Use Jellyfin Not Scanning New Files.

Media disappears after reboot

Check:

  1. whether the drive mounted
  2. whether the mount path changed
  3. whether Docker started before the mount became available
  4. whether the library still points to the same path
  5. whether permissions changed after remounting

Use:

Playback buffers or uses high CPU

Check:

  1. the active playback mode
  2. the conversion reason
  3. subtitles
  4. the selected audio track
  5. local or remote quality limits
  6. client compatibility
  7. hardware acceleration status

Use:

Remote playback does not connect

Check:

  1. whether Jellyfin works locally
  2. which remote-access method is configured
  3. firewall and VPN status
  4. DNS or hostname resolution
  5. certificate and reverse-proxy configuration, where used
  6. whether the server is exposed safely

Use:

1. Confirm storage is available

Run these checks on Ubuntu:

lsblk -f
df -h
findmnt

For a specific media path:

findmnt /path/to/media
ls -la /path/to/media

A directory can exist even when the drive that normally mounts there is absent. If the directory suddenly appears empty after reboot, verify the mount before editing the Jellyfin library.

Relevant guides:

2. Check folder permissions

Jellyfin needs access to every directory in the path, not only the final media folder.

Inspect the path with:

namei -l /path/to/media

For a native Jellyfin installation:

id jellyfin
ls -ld /path/to/media

For Docker, identify the container user and the host directory ownership. Also confirm the volume mapping.

Example:

volumes:
  - /srv/media/Movies:/media/movies:ro

The Jellyfin library must use /media/movies, not the host path.

Use:

Avoid using chmod 777 as a permanent fix. It hides the ownership or group problem and grants more access than Jellyfin normally needs.

3. Confirm the correct library path

For native Jellyfin, the library uses the host filesystem path.

For Docker, the library uses the path inside the container.

Compare:

Host path:      /srv/media/TV
Container path: /media/tv
Jellyfin path:  /media/tv

If the Docker mapping changes, Jellyfin does not automatically update the existing library path.

Test what the container can see using the container name from your deployment:

docker exec -it jellyfin ls -la /media/tv

If the host can see files but the container cannot, repair the volume mapping or container permissions before rescanning.

4. Diagnose scanning failures

A manual scan is useful only after the path and permissions are confirmed.

Work through:

  1. open the library settings and verify the path
  2. run a manual scan
  3. inspect scheduled tasks
  4. inspect the Jellyfin logs
  5. verify new-file ownership
  6. test one simple media filename

Use:

If older files are visible but newly copied files are missing, compare their ownership and permissions:

ls -l /path/to/media

The copy, download or automation process may be creating files under a different user or group.

5. Diagnose playback mode

While the problem file is playing:

  1. open the Jellyfin dashboard
  2. find the active session
  3. record Direct Play, Direct Stream or Transcoding
  4. record every stated conversion reason
  5. note video, audio and subtitle details

Use:

Do not assume high CPU means Jellyfin is malfunctioning. A required software video transcode can legitimately use several CPU cores.

6. Test subtitles and audio

Subtitles and audio frequently explain why apparently compatible video transcodes.

Use this controlled test:

  1. play the same scene with the original settings
  2. disable subtitles and replay
  3. select another audio track and replay
  4. check the dashboard after each change

If disabling subtitles changes the session to Direct Play, read Jellyfin Subtitles Causing Transcoding.

If changing audio removes conversion, the original audio codec or channel layout was unsupported by the client.

7. Compare clients

Test the same file on another maintained client.

A browser may support fewer combinations than a native Jellyfin client. If another client Direct Plays the file, the server and source file may be healthy.

Use Best Cheap Jellyfin Client for Direct Play when client compatibility is the repeated limitation.

Record the result rather than relying only on advertised codec support.

8. Check hardware acceleration

Configure hardware acceleration only after confirming that video conversion is required.

Use:

Verify:

Device visible to host
Device visible to container or VM
Jellyfin user has device access
Correct acceleration method selected
Active playback process uses the hardware encoder or decoder

A successful settings save does not prove the device is active during playback.

9. Review logs without guessing

Use logs to confirm the failing layer.

For a native service:

sudo journalctl -u jellyfin --since "30 minutes ago"

For Docker:

docker logs --since 30m jellyfin

Look for:

  • permission denied
  • path not found
  • mount or input/output errors
  • FFmpeg failures
  • unsupported codec or filter
  • hardware device errors
  • network or certificate errors

Capture the exact message and the action that produced it.

After a reboot, verify in this order:

findmnt
systemctl --failed
docker ps

Then confirm:

  • media storage mounted at the expected path
  • Docker or Jellyfin started successfully
  • the container can see its mapped paths
  • permissions remain correct
  • the library still points to the expected path

Starting Jellyfin before a required mount is available can make libraries appear empty even though the application itself is healthy.

Common mistakes

Repeatedly rescanning an unavailable path

A scan cannot repair a missing mount, incorrect Docker mapping or permission failure.

Changing ownership recursively without understanding the service users

This can break downloaders, Samba shares and other containers that share the same storage.

Converting the entire library after one playback failure

Test another client, subtitle track, audio track and quality setting first.

Enabling hardware acceleration without verification

Check the active session and process. Do not rely only on the configured checkbox.

Exposing Jellyfin publicly to solve remote access

Use a planned VPN or reverse-proxy setup rather than opening ports without security controls.

Missing files and permissions

Scanning and reboot problems

Playback and transcoding

Ubuntu deployment and maintenance

Remote access

Recap

Troubleshoot Jellyfin by identifying the failing layer:

  1. storage
  2. permissions
  3. path mapping
  4. library scanning
  5. client compatibility
  6. network access
  7. hardware acceleration

Collect evidence, make one change and repeat the same test. This prevents one fix from hiding another problem and avoids unnecessary library conversion or hardware replacement.

Jellyfin guide cluster

More Jellyfin fixes and setup guides

These guides link the main Jellyfin setup, permissions, remote access, direct play, and hardware topics together.