Troubleshooting

Troubleshooting

No cache SSD/NVMe is listed

The cache must be a separate non-rotational drive. Detected system drives, selected library drives and drives used by another storage layer are excluded. A drive without a usable serial number cannot be selected. Check the physical connection and reopen the panel.

A library partition is missing

It must be an ext4 data partition on a separate, non-system drive and already mounted under /run/media/, /media/ or /mnt/. Mount it in Desktop Mode and check that Steam sees its existing library, then reopen DeckyCache.

Enable its partition under Library drives first. You can then choose folders on it under Cache scope.

Format or selection is refused

Read the error in the panel. Close games, file managers and applications using that drive, and let Steam updates finish. Reopen the drive selector if the device list changed. Do not format the library HDD to resolve a cache-drive error.

Open CAS is unavailable / Waiting for cache

Check the selected SSD connection and compare uname -r with Compatibility. A kernel update requires a matching module bundle. Do not force-load an older module or format the SSD just to clear this message.

Cache space grows but there are few hits

The first read of uncached data normally comes from HDD. Repeated reads may be served from RAM before reaching Open CAS. Writes do not allocate new cache blocks in this release. Background reads inside the selected scope can populate cache. Occupancy alone does not prove a game read came from NVMe.

For a controlled check, close the game, restart normally, record Open CAS counters before launch, then load the same content and compare read hits and physical NVMe reads. Do not clear the SSD cache before that test.

A game appears even though I did not launch it

Steam or another process may have read its files in the background. Small entries are collapsed under Small fragments. See Everyday use for the attribution limits.

A non-Steam game is missing from Cached games

The Steam shortcut must point directly to an existing game executable on an enabled library partition. A shortcut to an external launcher may not expose the game folder and cannot be attributed automatically. You do not need to add the game or its artwork again.

Check Small fragments for entries below 16 MiB. New tracking starts with subsequent storage I/O; existing unclassified blocks are not counted retroactively. A warm launch may read entirely from RAM. The engine has 32 class slots per volume, shared by tracked game folders and selected folder roots. In whole-drive mode, files without a game slot can still use cache and appear under Other cached data.

Other cached data is large

The final tile includes blocks outside the current game list, such as unclassified data, selected-folder fallback classes and data retained from older versions. It does not include listed game entries, including Small fragments. Updating or changing scope does not silently erase earlier cached data.

Use Clear cache to discard all cached copies without formatting the SSD or deleting games. With write-around enabled, copying and installation writes no longer allocate cache lines. Reads for copying, unpacking or verification inside the selected scope can still fill cache.

A selected folder is refused or does not fill cache

Folders must be on an enabled library partition. The 32 Open CAS class slots per volume are shared by tracked games and selected folder roots. If no slot is free for a new folder, the selection is refused without broadening caching to the whole drive.

Reads already served from RAM do not reach Open CAS. Some direct or asynchronous reads cannot be associated with directory rules and bypass cache in folder mode. Use Entire selected drives if broader admission is more useful than folder filtering.

Cache is empty after a forced shutdown

A valid clean-shutdown seal is required for reuse. If it is missing or no longer matches, the cache starts cold. The original game files remain on HDD.

Steam temporarily shows no installed games

Do not format a drive or reinstall games. Close the game and check that the library drive is mounted and listed in Steam Storage. Restart Steam after a storage-path change. If the issue persists, leave the disks intact and collect the service log.

Getting useful logs

In Desktop Mode:

uname -r
systemctl status deckycache.service
journalctl -b -u deckycache.service --no-pager

Include the plugin version and the exact error when reporting a problem. Redact personal paths and drive serial numbers before sharing logs or screenshots.