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:

{
  "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 ✅

# 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 ✅

# 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:

{
  "$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

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 ✅

Get-Content "lib\Release\net11.0\startup.json"

Expected Output:

{
  "Paths": {
    "DataDir": "C:/ProgramData/jellyfin",
    ...
  }
}

Test 2: Verify Runtime Generation

# 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) ✅

{
  "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

{
  "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

{
  "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

{
  "Paths": {
    "DataDir": "D:/MyCustom/Jellyfin",
    "CacheDir": "E:/FastSSD/Cache"
  }
}

Option 2: Use environment variables

$env:JELLYFIN_DATA_DIR = "D:/MyCustom/Jellyfin"

Option 3: Use command-line arguments

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

# 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