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"

The build (CMake) fails

Symptom	Cause	Fix
Could not find a configuration file for package "OpenJPEG" that is compatible with requested version "2.5" and .../OpenJPEGConfig.cmake, version: unknown	the Debian/Ubuntu libopenjp2-7-dev package ships OpenJPEGConfig.cmake without a OpenJPEGConfigVersion.cmake, so CMake cannot compare versions	current CMakeLists.txt already falls back to an unversioned find_package(OpenJPEG); if you still see it, you are on an older checkout - update, or set -DOpenJPEG_DIR=<path with OpenJPEGConfig.cmake>
Could NOT find OpenJPEG / Could NOT find PNG	the -dev packages are missing	sudo apt-get install libopenjp2-7-dev libpng-dev
Could NOT find GTest	the test sources are present but GoogleTest is not	sudo apt-get install libgtest-dev, or configure with -DBUILD_TESTING=OFF to skip the tests
Qt 6 not found, GUI target skipped	qt6-base-dev is not installed	install it, or ignore it - the CLI and batch engine do not need Qt

On Windows (MSYS2) the same errors mean the mingw-w64-x86_64-* packages are missing; see Installation.

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

Interrupted runs, .part files and sanity limits

• The run stopped early (exit 10). Ctrl+C is handled: the current record is finished, the log line says interrupted: stopping before record N and the summary ends with [interrupted]. Just start the same command again - every file is renamed into place when it is complete, so the outputs that are there are complete and the run resumes by skipping them.
• *.part files in the output directory. Each PNG/.j2c is written as <name>.part and renamed over the target when it is finished. A .part file is therefore the leftovers of a killed run (Ctrl+C, power loss, taskkill), never a valid output: it is safe to delete, and no later run mistakes it for a finished PNG (that is why the file names of the outputs are unchanged).
• record N ... announces a body of X bytes, which is not plausible (exit 9) or the codestream declares WxH with N component(s), which is not plausible: the entry or the cached block is corrupt (a flipped byte in the header is enough). The record is skipped instead of allocating gigabytes; run with -v to see the index and decode the texture in the viewer again.
• the body file is missing or has another size than the record announces with --dry-run. The dry run predicts the failure a real run would hit.

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).