pgsql-jellyfin/docs/PATH_FIX_GUIDE.md

Windows Path Fix for Jellyfin PostgreSQL Database

Problem

Logger shows Linux paths on Windows machine:

[WRN] Image not found at "/var/lib/jellyfin/metadata/People/D/David L.M. McIntyre/folder.jpg"

This happens because:

1. Paths are stored in the database (not computed at runtime)
2. You likely migrated from a Linux installation or imported data with Linux paths
3. The database contains absolute Linux paths that don't exist on Windows

Root Cause

The ImageInfo.Path and BaseItemEntity.Path fields store absolute file paths in the database. When you migrate from Linux to Windows, these paths aren't automatically converted.

Solutions

Solution 1: Run SQL Script to Fix Paths (Quick Fix)

1. Backup your database first!

   pg_dump -h localhost -U jellyfin -d jellyfin > jellyfin_backup_$(Get-Date -Format 'yyyyMMdd_HHmmss').sql
   

2. Run the path fix script:

   psql -h localhost -U jellyfin -d jellyfin -f fix_windows_paths.sql
   

3. Review the preview - The script shows what will be changed without modifying data

4. Uncomment the UPDATE statements in the script and run again to apply changes

5. Restart Jellyfin

Solution 2: Rebuild Metadata (Clean Approach)

If you have a small library, it may be easier to rebuild metadata:

1. Dashboard → Library → Scan All Libraries
2. Dashboard → Scheduled Tasks → "Scan Media Library" → Run
3. This will recreate image paths with correct Windows paths

Solution 3: Manual Database Query (For specific items)

If only a few items are affected, you can fix them manually:

-- Find People with Linux paths
SELECT "Id", "Path" 
FROM library."ImageInfos" 
WHERE "Path" LIKE '/var/lib/jellyfin/metadata/People/%';

-- Update a specific Person's image path
UPDATE library."ImageInfos"
SET "Path" = 'C:\ProgramData\jellyfin\data\metadata\People\D\David L.M. McIntyre\folder.jpg'
WHERE "Id" = <your_id>;

Prevention

To avoid this issue in the future:

1. Use consistent paths when migrating between OSes
2. Consider using virtual paths (e.g., %MetadataPath%\People\... instead of absolute paths)
3. Test migrations with a small dataset first

Notes

• Windows accepts both forward slashes (/) and backslashes (\) in paths
• However, the logger will show whatever is stored in the database
• The script converts /var/lib/jellyfin → C:/ProgramData/jellyfin/data
• Adjust the script if your Windows Jellyfin data directory is different

Checking Your Current Paths

Run this to see what paths are in your database:

-- Show sample ImageInfo paths
SELECT "Id", "Path" 
FROM library."ImageInfos" 
WHERE "Path" LIKE '/var/%' OR "Path" LIKE '/usr/%'
LIMIT 10;

-- Count Linux vs Windows paths
SELECT 
    COUNT(CASE WHEN "Path" LIKE '/var/%' OR "Path" LIKE '/usr/%' THEN 1 END) AS linux_paths,
    COUNT(CASE WHEN "Path" LIKE 'C:%' OR "Path" LIKE 'D:%' THEN 1 END) AS windows_paths,
    COUNT(*) AS total_paths
FROM library."ImageInfos";

Your Specific Case

Based on the error:

/var/lib/jellyfin/metadata/People/D/David L.M. McIntyre/folder.jpg

Should be converted to:

C:\ProgramData\jellyfin\data\metadata\People\D\David L.M. McIntyre\folder.jpg

Or if your Jellyfin data directory is different, adjust accordingly.