pgsql-jellyfin/docs/LINUX_PATH_ISSUE_SUMMARY.md

# Summary: Linux Paths Showing on Windows

## ✅ Root Cause Identified

Your database is **correctly** storing virtual paths:
```
%MetadataPath%\People\D\David L.M. McIntyre\folder.jpg
```

However, the logs show Linux paths:
```
/var/lib/jellyfin/metadata/People/D/David L.M. McIntyre/folder.jpg
```

**Why?** The `system.xml` configuration file contains Linux paths that are used to expand the virtual `%MetadataPath%` placeholder.

## 📂 Files to Check

### **1. system.xml** (Most likely culprit)
**Location:** `C:\ProgramData\jellyfin\config\system.xml`

Look for:
```xml
<MetadataPath>/var/lib/jellyfin/metadata</MetadataPath>
```

Should be:
```xml
<MetadataPath></MetadataPath>
```
or
```xml
<MetadataPath>C:\ProgramData\jellyfin\data\metadata</MetadataPath>
```

### **2. encoding.xml** (If transcoding shows Linux paths)
**Location:** `C:\ProgramData\jellyfin\config\encoding.xml`

Look for:
```xml
<TranscodingTempPath>/var/tmp/jellyfin</TranscodingTempPath>
```

Should be empty or a Windows path.

### **3. database.xml** (Less common)
**Location:** `C:\ProgramData\jellyfin\config\database.xml`

Check for any Linux paths in connection strings or options.

## 🔧 How to Fix

### **Option 1: Use PowerShell Script** (Automated - Recommended)

```powershell
# Check what needs to be fixed (safe, no changes)
.\FixJellyfinPaths.ps1 -DryRun

# Apply fixes (with confirmation prompt)
.\FixJellyfinPaths.ps1

# Apply fixes without prompts
.\FixJellyfinPaths.ps1 -Force

# Custom paths
.\FixJellyfinPaths.ps1 -ConfigPath "D:\Jellyfin\config" -DataPath "D:\Jellyfin\data"
```

### **Option 2: Edit system.xml Manually**

1. **Stop Jellyfin**
2. Open `C:\ProgramData\jellyfin\config\system.xml`
3. Find `<MetadataPath>` and change from Linux path to empty or Windows path
4. Save
5. **Start Jellyfin**

### **Option 3: Via Dashboard** (UI)

1. Dashboard → Advanced → Paths
2. Clear or update the **Metadata path** field
3. Save
4. Restart Jellyfin

## 🧪 How the Path Resolution Works

```
Database Stores:  %MetadataPath%\People\D\David L.M. McIntyre\folder.jpg
                            ↓
                  (Expand virtual path)
                            ↓
system.xml has:   /var/lib/jellyfin/metadata  ← PROBLEM!
                            ↓
                  (Combine paths)
                            ↓
Final Path:       /var/lib/jellyfin/metadata\People\D\David L.M. McIntyre\folder.jpg
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ (Linux path from config!)
```

**After Fix:**
```
Database Stores:  %MetadataPath%\People\D\David L.M. McIntyre\folder.jpg
                            ↓
                  (Expand virtual path)
                            ↓
system.xml has:   (empty) → Use default: C:\ProgramData\jellyfin\data\metadata
                            ↓
                  (Combine paths)
                            ↓
Final Path:       C:\ProgramData\jellyfin\data\metadata\People\D\David L.M. McIntyre\folder.jpg
                  ✓ Correct Windows path!
```

## 📍 Code Locations

The path expansion happens in:

1. **`ServerConfigurationManager.cs:78-84`**
   ```csharp
   private void UpdateMetadataPath()
   {
       ((ServerApplicationPaths)ApplicationPaths).InternalMetadataPath = 
           string.IsNullOrWhiteSpace(Configuration.MetadataPath)
               ? ApplicationPaths.DefaultInternalMetadataPath
               : Configuration.MetadataPath;  // ← Uses system.xml value
   }
   ```

2. **`ServerApplicationPaths.cs:63`**
   ```csharp
   public string PeoplePath => Path.Combine(InternalMetadataPath, "People");
   ```

## 🔍 Verification

After applying the fix, check the logs. The error should change from:
```
[WRN] Image not found at "/var/lib/jellyfin/metadata/People/..."
```

To:
```
[WRN] Image not found at "C:\ProgramData\jellyfin\data\metadata\People\..."
```

(The file might still not exist, but at least the path will be correct!)

## 📝 Prevention

When migrating from Linux to Windows in the future:
1. Don't copy `system.xml` directly
2. Let Jellyfin generate a new config file
3. Or manually edit paths before starting Jellyfin
4. Use empty values for paths to let Jellyfin use OS-appropriate defaults

## 🎯 TL;DR

- ✅ Database is correct (uses `%MetadataPath%`)
- ❌ `system.xml` has Linux paths
- 🔧 Fix: Clear `<MetadataPath>` in system.xml
- 🔄 Restart Jellyfin