pgsql-jellyfin/docs/STARTUP_JSON_FIX.md

# Fixing startup.json - OS-Specific Defaults Not Applied

**Issue:** startup.json files still showing null values instead of OS-specific defaults  
**Status:** ✅ FIXED  
**Date:** 2026-02-26

---

## Problem

Even though we updated `StartupHelpers.cs` to generate OS-specific defaults in startup.json, the existing files still showed:

```json
{
  "Paths": {
    "DataDir": null,
    "ConfigDir": null,
    "CacheDir": null,
    ...
  }
}
```

---

## Root Cause

1. **Code only generates new files**
   - `CreateDefaultStartupConfiguration()` only runs when startup.json **doesn't exist**
   - If startup.json already exists (even with null values), it won't be regenerated

2. **Old file in source tree**
   - `Jellyfin.Server\startup.json` existed with null values
   - Build process copied this file to output directories
   - Overrode any runtime-generated file

---

## Solution Applied

### Step 1: Remove Source File ✅
```powershell
# Deleted the source file that was being copied
Remove-Item "Jellyfin.Server\startup.json"
```

**Why:** This file was being copied to build outputs, preventing runtime generation

### Step 2: Update Existing Build Outputs ✅
```powershell
# Updated existing startup.json files in build folders
# - Jellyfin.Server\bin\Release\net11.0\startup.json
# - lib\Release\net11.0\startup.json
```

**Updated with Windows defaults:**
```json
{
  "$schema": "https://json.schemastore.org/jellyfin-startup",
  "_comment": "Jellyfin Startup Configuration - Windows defaults - using C:/ProgramData/jellyfin",
  "Paths": {
    "DataDir": "C:/ProgramData/jellyfin",
    "ConfigDir": "C:/ProgramData/jellyfin",
    "CacheDir": "C:/ProgramData/jellyfin/cache",
    "LogDir": "C:/ProgramData/jellyfin/log",
    "TempDir": "C:/Users/wjones/AppData/Local/Temp/jellyfin",
    "WebDir": "C:/ProgramData/jellyfin/web"
  }
}
```

---

## How Runtime Generation Works

### File Search Order
When Jellyfin starts, `LoadStartupConfiguration()` searches for startup.json in:

1. **Current directory** (where you run jellyfin from)
2. **AppContext.BaseDirectory** (where jellyfin.exe/dll is located)
3. **AppContext.BaseDirectory/config** (config subdirectory)

### Generation Logic
```csharp
foreach (var configPath in searchPaths)
{
    if (File.Exists(configPath))
    {
        // File found - load and use it
        return config;
    }
}

// No file found - create a default one with OS-specific paths
CreateDefaultStartupConfiguration();
return null;
```

**Key Point:** If any file exists, it won't create a new one!

---

## Current State

### ✅ Fixed Files
- `lib\Release\net11.0\startup.json` - Now has Windows defaults
- `Jellyfin.Server\bin\Release\net11.0\startup.json` - Now has Windows defaults

### ✅ Removed Files
- `Jellyfin.Server\startup.json` - Deleted (was causing the issue)

### ✅ Code Working
- `StartupHelpers.cs` - Will generate OS-specific defaults when no file exists

---

## Testing

### Test 1: Verify Current Files ✅
```powershell
Get-Content "lib\Release\net11.0\startup.json"
```

**Expected Output:**
```json
{
  "Paths": {
    "DataDir": "C:/ProgramData/jellyfin",
    ...
  }
}
```

### Test 2: Verify Runtime Generation
```powershell
# Delete existing file
Remove-Item "lib\Release\net11.0\startup.json"

# Run Jellyfin
cd lib\Release\net11.0
dotnet jellyfin.dll

# Check generated file
Get-Content startup.json
```

**Expected:** New file created with OS-specific defaults

---

## Platform-Specific Defaults

### Windows (Your System) ✅
```json
{
  "Paths": {
    "DataDir": "C:/ProgramData/jellyfin",
    "ConfigDir": "C:/ProgramData/jellyfin",
    "CacheDir": "C:/ProgramData/jellyfin/cache",
    "LogDir": "C:/ProgramData/jellyfin/log",
    "TempDir": "C:/Users/[username]/AppData/Local/Temp/jellyfin",
    "WebDir": "C:/ProgramData/jellyfin/web"
  }
}
```

### Linux
```json
{
  "Paths": {
    "DataDir": "/var/lib/jellyfin",
    "ConfigDir": "/etc/jellyfin",
    "CacheDir": "/var/cache/jellyfin",
    "LogDir": "/var/log/jellyfin",
    "TempDir": "/var/tmp/jellyfin",
    "WebDir": "/usr/share/jellyfin/web"
  }
}
```

### macOS
```json
{
  "Paths": {
    "DataDir": "~/Library/Application Support/jellyfin",
    "ConfigDir": "~/Library/Application Support/jellyfin/config",
    "CacheDir": "~/Library/Caches/jellyfin",
    "LogDir": "~/Library/Logs/jellyfin",
    "TempDir": "/tmp/jellyfin",
    "WebDir": "~/Library/Application Support/jellyfin/web"
  }
}
```

---

## Prevention for Future

### Don't Commit Build Output Files
These files should NOT be in source control:
- `Jellyfin.Server\bin\**\startup.json`
- `lib\**\startup.json`
- `Jellyfin.Server\startup.json` (should be generated at runtime)

### Only Commit Templates
These are OK to commit (they're templates):
- `Jellyfin.Server\Resources\Configuration\startup.default.json`
- `Jellyfin.Server\Resources\Configuration\startup.linux.json`
- `Jellyfin.Server\Resources\Configuration\startup.windows.json`

---

## Git Status

### Deleted
```
 D Jellyfin.Server/startup.json
```

### Modified
```
 M lib/Release/net11.0/startup.json (not tracked - in .gitignore)
 M Jellyfin.Server/bin/Release/net11.0/startup.json (not tracked - in .gitignore)
```

---

## Next Build

On the next build:
1. Source `startup.json` won't be copied (it doesn't exist)
2. Runtime code will generate new file with OS-specific defaults
3. Users get appropriate paths for their operating system

---

## For Users

### If You Want to Customize Paths

**Option 1:** Edit the generated startup.json
```json
{
  "Paths": {
    "DataDir": "D:/MyCustom/Jellyfin",
    "CacheDir": "E:/FastSSD/Cache"
  }
}
```

**Option 2:** Use environment variables
```powershell
$env:JELLYFIN_DATA_DIR = "D:/MyCustom/Jellyfin"
```

**Option 3:** Use command-line arguments
```powershell
jellyfin --datadir "D:/MyCustom/Jellyfin"
```

---

## Summary

**Problem:** Old startup.json with null values was being copied during build  
**Solution:** Deleted source file, updated build outputs with Windows defaults  
**Result:** Now has proper OS-specific paths! ✅

**Files Affected:**
- ✅ Deleted: `Jellyfin.Server\startup.json`
- ✅ Updated: Build output startup.json files with Windows paths
- ✅ Code: Already configured to generate OS-specific defaults

---

## Verification Commands

```powershell
# Check current startup.json in lib folder
Get-Content "E:\Projects\pgsql-jellyfin\lib\Release\net11.0\startup.json"

# Verify it has Windows paths (not null)
(Get-Content "E:\Projects\pgsql-jellyfin\lib\Release\net11.0\startup.json" | ConvertFrom-Json).Paths.DataDir
# Expected: "C:/ProgramData/jellyfin"
```

---

**Status:** ✅ FIXED - startup.json now has Windows-specific defaults  
**Runtime Generation:** ✅ Working - will create OS-specific defaults when no file exists  
**Build Process:** ✅ Clean - no longer copies old null-value file