Troubleshooting Settings Startup GPU

Troubleshooting — Settings, Startup & GPU

This page covers three classes of problem that share a root cause in how Sucrose stores state outside its own JSON files: settings that appear to reset themselves, autostart that won't turn off (because it's a Task Scheduler task, not a registry Run key), and GPU/black-screen issues tied to the Windows per-app GPU-preference registry key. For renderer/runtime problems, see Troubleshooting-Common.

Contents

• Settings reset themselves or won't save
• A setting change doesn't persist
• Autostart won't turn off
• GPU preference & black-screen issues
• Where state actually lives (quick map)

---

Settings reset themselves or won't save

Sucrose stores all of its configuration as small JSON files under %AppData%\Sucrose\Setting\, one file per category (General.json, Engine.json, Portal.json, Library.json, Backgroundog.json, Update.json, Hook.json, Cycling.json, System.json, Warehouse.json, Aurora.json, Objectionable.json, Kernel.json, Donate.json). There is no monolithic config file.

Auto-reset of corrupt files

Every settings manager runs a self-healing check (ControlFile) when it loads a file. If a settings file is missing, empty, or invalid JSON, it is automatically reset to an empty document ({ "Properties": {} }). So if a file got truncated (for example by a power loss mid-write, or a bad hand-edit), Sucrose silently restores defaults for that category on next read. This is intentional and prevents a corrupt file from crashing the app — but it looks like "my settings disappeared." See Settings-Persistence.

Fix: if you have a backup, use Settings → System → Setting Backup → Import to restore your *.json files. See Backup-Restore-Reset.

Hand-editing JSON safely

The JSON shape is a single object with one Properties dictionary:

{
  "Properties": {
    "Culture": "EN",
    "AppVisible": true,
    "WallpaperVolume": 100
  }
}

When editing by hand, keep these rules in mind:

• Enums are stored as their string name, not their integer. For example a PerformanceType value is written as "Close", not 0. Use the member name. See Settings-All-Keys.
• Out-of-range numbers are silently clamped on read (not rewritten). If you put WallpaperVolume: 250 it is read back as 100; the file is not corrected on disk.
• Stray doubled braces ({{ / }}) are stripped defensively on read/write, but malformed JSON beyond that triggers the auto-reset above.
• Close all Sucrose processes before editing (see Backup-Restore-Reset), because the app may rewrite the file.

---

A setting change doesn't persist

If you change a value in the Portal (or by hand) and it reverts:

• The write may have failed silently. All settings writes swallow exceptions (catch { }). A file that is locked or permission-denied silently fails to persist — no error is shown. Causes include the file being open in another program, a read-only attribute, antivirus/controlled-folder-access locking %AppData%\Sucrose, or a roaming-profile sync conflict. See Settings-Persistence.
  • Fix: close any program holding the file, clear the read-only attribute, and exclude %AppData%\Sucrose from controlled-folder-access / aggressive AV scanning.
• Cross-process contention. Reads and writes are guarded by a named mutex keyed to the MD5 of each file path, so the many Sucrose processes don't corrupt each other. This is safe, but if a process hangs holding the mutex, writes can stall — fully exit Sucrose (all Sucrose* processes) and retry. See Single-Instance-Mutexes.
• It was clamped/normalized. As above, out-of-range values are clamped, and enums are normalized to their canonical member name on read — so the saved value may differ from what you typed. See Settings-All-Keys.

---

Autostart won't turn off

There are two different autostart mechanisms, and the right removal step depends on which one you used. The mode is the Application Startup option on the General settings page (RunStartup): 0=None, 1=Normal, 2=Priority, 3=Scheduler.

Startup mode	Mechanism	Where it lives
1=Normal	Per-user Run key (Commandog Startup)	HKCU\...\CurrentVersion\Run
2=Priority	Machine/priority startup (Commandog StartupM/StartupP)	Run key / approved startup
3=Scheduler	Windows Task Scheduler (Commandog Scheduler)	Scheduled task, not a registry Run key

The Scheduler task

When you choose Scheduler, Sucrose creates a Windows Task Scheduler task:

• Task name: Autorun for Sucrose
• Description: Sucrose Wallpaper Engine
• Folder: the \Sucrose\ task folder (or the root folder, depending on the creating command)
• Trigger: logon trigger scoped to the current user
• Settings: does not stop on battery, no execution time limit

Because this is not a registry Run entry, disabling startup items in Task Manager's Startup tab will not remove it. To remove a stuck autostart:

1. Set Application Startup to None in Settings → General (preferred — this issues the Commandog Scheduler Delete command), or
2. Open Task Scheduler, find and delete the Autorun for Sucrose task (check both the root and the \Sucrose\ folder).

See Theme-Tray-Startup, Settings-General, Commandog-Dispatcher, and Automation-Examples.

---

GPU preference & black-screen issues

Beyond the Windows DirectX GPU-preference key described below, Sucrose stores no settings in the registry. That one key is Windows' own per-app GPU setting.

• Key: HKEY_CURRENT_USER\Software\Microsoft\DirectX\UserGpuPreferences
• Format: a semicolon-delimited string per app path, e.g. GpuPreference=<n>;
• Driven by: the Engine.GraphicPreference setting (HighPerformance by default). Sucrose writes this so its engine processes use the chosen adapter.

When a black screen or wrong-GPU rendering correlates with multi-GPU laptops (integrated + discrete):

1. Toggle Hardware Acceleration in Settings → Wallpaper (default true) and re-apply the wallpaper. See Troubleshooting-Common.
2. In Windows Settings → System → Display → Graphics, set the Sucrose engine executables (e.g. Sucrose.Live.CefSharp.exe, Sucrose.Live.MpvPlayer.exe, Sucrose.Live.WebView.exe) to your preferred GPU. This edits the same UserGpuPreferences key.
3. If the value is wrong, you can clear the relevant GpuPreference entries under that registry key and let Sucrose re-write them.

See Data-Locations for the full registry/file map and Engine-Comparison for which engines are GPU-heavy.

flowchart LR
    Portal["Portal / settings managers"] -->|writes| Settings["Settings JSON<br/>%AppData%/Sucrose/Setting/*.json<br/>(auto-reset if corrupt)"]
    Cmd["Commandog Scheduler command"] -->|creates| Startup["Task Scheduler task<br/>'Autorun for Sucrose'<br/>(not a registry Run key)"]
    Graphic["Engine.GraphicPreference"] -->|writes| GPU["HKCU DirectX<br/>UserGpuPreferences<br/>(Windows per-app GPU)"]

Loading

---

Where state actually lives (quick map)

State	Stored in	Notes
All app settings	%AppData%\Sucrose\Setting\*.json	Auto-reset if corrupt; writes can fail silently if locked
Autostart (Scheduler mode)	Task Scheduler task Autorun for Sucrose	Not a registry Run key
Autostart (Normal/Priority)	HKCU\...\Run / approved startup	Via Commandog Startup commands
GPU preference	HKCU\Software\Microsoft\DirectX\UserGpuPreferences	Windows' own per-app setting
Personal Access Token	Objectionable.json (plaintext)	Sensitive — see Privacy-Telemetry
Uninstall entry	HKCU\...\Uninstall\Sucrose	Created by installer; removed by Sucrose.Undo.exe

See the full reference in Data-Locations and Settings-Persistence.

---

See also

• Troubleshooting-Common
• Settings-Persistence
• Backup-Restore-Reset
• Data-Locations
• Theme-Tray-Startup