Troubleshooting

Start by recording csha --version, the operation mode, and the first error
message. Remove key values, private PEM contents, and payload text before sharing
logs. Commands below use ./build/csha from the repository root.

CMake and dependencies

Symptom	What to check
`Could NOT find OpenSSL`	Install OpenSSL development files. On macOS, the project asks Homebrew for `openssl@3`; for another prefix, configure with `-DOPENSSL_ROOT_DIR=/path/to/openssl`.
`OpenCVConfig.cmake` not found	Install OpenCV, or set `OpenCV_DIR` to the directory containing that config file.
`Package libzip was not found`	Install both libzip development files and pkg-config; for a custom prefix, set `PKG_CONFIG_PATH` to its `lib/pkgconfig` directory.
Named modules/compiler error	Use upstream Clang 16+ and a fresh Ninja build. AppleClang is not supported; on macOS install Homebrew LLVM.
Crypto++ not found	Install Crypto++ 8.9+ development files and ensure pkg-config can find them.
Catch2 3 or Python not found	Install the test dependencies, or use a separate build configured with `-DBUILD_TESTING=OFF`.
Generator does not match the previous generator	Use a new build directory when switching between Ninja and Makefiles.
Executable cannot load a shared library after installation	Keep the required shared libraries installed on the target machine; the install target copies only the executable.

For example, an explicit OpenSSL prefix in a separate CLion build profile:

cmake -S . -B build-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug -DOPENSSL_ROOT_DIR=/path/to/openssl
cmake --build build-debug --parallel

Replace the example path with the actual installation. See
Building and installation for complete dependency lists.

Images, archives, and passwords

Symptom	Likely cause and next step
`Empty image provided` or image cannot be read	Confirm the path and that the file is an intact image. A renamed file is not necessarily a PNG.
Authentication/decryption failure	Use the matching decoder, key input, AES mode, and derivation. Check that the encrypted PNG has not been resized or edited.
`Image does not unlock this map, or key slots are damaged`	Use either original image credential with the original dimensions and decoded pixels. A screenshot of the credential is a different key.
`Image-pair map payload exceeds single-map capacity`	Keep input at or below 196,432 bytes for AES or 196,288 for other ciphers, or choose a different storage format.
`Use either --image or --image-data-url`	Supply exactly one image input source.
`Cannot read data URL file`	`@` must be followed by the actual path; quote the whole argument if it contains spaces.
Data URL output requires a single-image mode	Use `ez` for a ZIP in one image; `fz`/`fdz` are not data-URL export modes.
PNG and data URL output paths conflict	Give the PNG and text file distinct paths.
Large `fz` recovery fails	Keep the master PNG and its matching `.chunks` directory together, with every numbered chunk intact; use matching passwords and keys.
Cipher option rejected	Use a name from `--list-ciphers`. Non-AES encoding does not accept `-A`, `-k DIRECT`, or `-k FIXED`.
Restored `ef` output includes log text	`di` prints a labeled result and diagnostics; it does not write raw decoded bytes to `-o`. Use `ez`/`dz`, image-pair file output, or the C++ API for exact files.

Use cmp original.zip restored.zip or compare hashes to check an archive
round trip. For image-pair files, pass -o restored.bin to the fd command.
Do not infer a complete binary recovery from readable terminal output alone.

Current CLI limitations

These describe the current implementation; they are not instructions to change
or bypass its validation.

An unknown -M value falls back to ordinary f. Use a documented mode name
and check output before relying on an automated command.

AES and derivation names are uppercase. Unrecognized -A or -k values keep
the current/default selection rather than producing a validation error.

-e and -d add validation requirements; they do not select the mode. The
examples use -M directly.

The legacy short -x option is inconsistent with its argument handling.
Use -M dm -i map.png to inspect seed metadata.

mtz writes seed_data.txt in the current directory and invokes the system
zip command through a shell. It is a legacy metadata export path, not a
general encrypted archive decoder; avoid automation with untrusted paths.

Blob Streams

Symptom	What to check
Peer verification fails	Each side needs the other device's verified public certificate, plus its own matching key/certificate pair. Check certificate expiry.
Relay connects but handshake times out	Start one initiator and one responder with the same room within the 10-second setup window.
Connection remains open after local input ends	EOF closes one direction. The other peer must also finish sending before the full connection closes.
Truncation error	TCP ended without authenticated TLS shutdown; discard provisional atomic-file output.
Address already in use	Choose another listening port or stop the process that owns the intended port.

The built-in relay serves one pair and exits. Restart it for another session.
The room name routes a session; it does not replace certificate verification.
See Blob Streams for direct and relay workflows.

Docker PNGs

Symptom	What to check
Docker command fails	Confirm the Docker CLI and daemon are available and the image exists locally; `--pull` explicitly enables a registry pull.
Key file rejected	Use the generated 32-byte binary key, not a PEM identity or a typed password file.
Output already exists	Choose a new output path. These commands intentionally refuse to overwrite key, PNG, and restored archive files.
Inspect/restore fails with a wrong key or modified PNG	Preserve the original key and PNG. Authentication must finish before a restored archive can be used.
Load succeeds but run fails	Check the image platform, entrypoint, command, and requested Docker runtime options.
Disk fills during pack/load	Allow space for the archive temporary file, PNG or restored output, and Docker's own storage.

restore does not require Docker and can help separate archive recovery from
Docker runtime issues. inspect verifies the full archive; it is not just a
quick unauthenticated header read.

Reproduce the project's checks

ctest --test-dir build --output-on-failure
ctest --test-dir build -R 'csha_help|csha_version|csha_pair_data_url' --output-on-failure

The Docker CLI test uses a deterministic Docker subprocess fixture. It does not
prove that a particular real image runs on your host. The optional real-daemon
check is documented in Docker images as PNGs.

Troubleshooting

CMake and dependencies#

Images, archives, and passwords#

Current CLI limitations#

Blob Streams#