Troubleshooting

Troubleshooting

Start with the exit code - it is the error category (full table on Usage) and it usually tells you which page to read:

SLTextureDecoder --cache-dir "D:\FS Cache\texturecache" --limit 5 -v
"exit code: $LASTEXITCODE"

Nothing is converted

Symptom	Cause	Fix
not a directory: <path> (exit 2)	the argument is a file or does not exist	pass the folder that holds texture.entries
no texture.entries in <dir> / no texture.cache in <dir> (exit 2)	wrong folder, or the viewer never cached anything there	see the locations on Installation; the folder must contain both files plus the 0..f shards
texture.entries is too small / is truncated (exit 9)	the file is a fragment (copied while the viewer was writing)	copy the whole cache again with the viewer closed
0 PNG written, selected 0	every record is a free slot (mBodySize <= 0) or --complete-only filtered them all out	drop --complete-only
many record N ... has no body errors	free slots whose mBodySize is 0 - normal in a sparse cache	ignore, or use --complete-only

The output does not look like the texture

Symptom	Why	What to do
the file is named <uuid>.partial.png	the codestream is truncated in the cache (about 58 % of a typical cache, group B on Cache format)	expected: the picture is best effort, the missing detail is simply not on disk. Decode the same texture in the viewer, then re-run the tool to get the new cache entry
the picture is blurry but recognisable	the same thing, seen through the lenient OpenJPEG pass	as above
5 components, dropping the surplus plane warning	the codestream has a fifth, non alpha plane whose meaning is unknown	informational; alpha is component 3 and is kept
the output is 8 bit though the texture is 16 bit per component	the tool always writes 8 bit RGBA	by design
a texture is missing from the output	the record is a free slot, or it failed (grep the log for ERROR)	run with -v on a small --limit to see it
subsampled components are not supported	a codestream variant the viewer never writes	report it with the record index and the log line

Runs are slow

• The CLI (SLTextureDecoder.exe) is single threaded by design. For speed use the batch mode of the GUI binary:

  SLTextureDecoderGUI.exe --batch --jobs 4 --cache-dir "D:\FS Cache\texturecache" --out-dir D:\textures

  Measured 2.7x on a 2 core / 4 thread CPU; see Performance.

• A single texture is decoded by one thread (single tile codestream), so more threads than logical CPUs never help - the pool is capped at 32.

• Writing the PNGs is a large part of the work; put the output directory on a fast disk, not on the same spinning disk as the cache.

• Interrupted? Just start the same command again: existing PNGs are skipped (that is the default, --overwrite turns it off).

--id / --index problems

Message	Cause
texture <uuid> is not in this cache (exit 3)	the id is not in texture.entries; you may be reading a different cache directory, or the viewer has already replaced that entry
record N is out of range, the cache holds M records (exit 3)	--index is not < mEntries; note that indices are not sorted by anything - get one from a -v log line
body file not found: ... (exit 3)	mBodySize > 0 but the shard file is gone (cache cleanup); the record is undecodable

Cache level errors (exit 4, 5)

• texture.cache is too small for entry N (4) - the file is shorter than N * 600; the cache was truncated or is being rewritten by the viewer.
• header block of entry N is ... (4) - a short read at that offset (I/O error, network drive, file replaced underneath).
• body file ... holds X bytes but mBodySize is Y (5) - the record and the file disagree, typically because the viewer wrote the record but not the body yet. Copy the cache with the viewer closed and try again.

The GUI does not start

Symptom	Fix
nothing happens / "Qt6Widgets.dll was not found"	Qt 6 is linked dynamically: put C:\msys64\mingw64\bin on PATH or run windeployqt build/bin/SLTextureDecoderGUI.exe
the window opens but the preview stays empty	the PNG cannot be read; the tooltip shows the file name - check the file is there and complete
"Not a usable cache: ..." under the path fields	the same messages as above, shown inside the window instead of the console
closing the window does not work	a texture is still being decoded; the dialog says so - close it again in a moment (the window waits up to 15 s)
the settings are odd / an old output path is stuck	delete HKCU\Software\SLTextureDecoder\GUI

Getting more information

• -v (Verbose log in the GUI) logs one line per record: index, uuid, file name, size, components and the OpenJPEG diagnostics.

• The diagnostics of a lenient decode are appended to the verbose line, e.g. [segment too long (78) with max (35) for codeblock ...] - expected for truncated records.

• Redirect both streams to keep everything:

  SLTextureDecoder --cache-dir "D:\FS Cache\texturecache" --out-dir D:\textures -v > out.log 2>&1

• A bug report is much easier to act on with: the version (--version), the exit code, the [INFO] cache ... line, one failing record's full verbose line, and texture.entries's encoder string. Please do not attach the decoded textures - they belong to their creators (see Legal notice).