-
Notifications
You must be signed in to change notification settings - Fork 2
Troubleshooting
Common errors and what to do about them. Open an issue if your case isn't here.
The .pjg was made by a different major version of packJPG. The current v4.0 LTS line accepts version byte 0x28 (= decimal 40) only. Other version bytes mean a different format generation.
Fix:
| Version byte | Made by | What to do |
|---|---|---|
0x1F (31) |
packJPG v3.1 family | Decode with v3.1d, re-encode with v4.0e, keep both .pjg. |
0x28 (40) |
v4.0 LTS family | Should work — re-download/recheck file integrity. |
0x29+ |
Hypothetical future major | Update packJPG to a newer version. |
v4.0/v4.0a archives decode transparently under v4.0e. v4.0b/c/d/e archives are byte-exact equivalents — any v4.0b+ build decodes them.
The .pjg contains a sub-marker byte that this build doesn't recognize. Sub-markers are byte values in 0x00 .. 0x13 placed before the version byte. Currently used:
-
0x00— custom compression settings (8 bytes follow) -
0x01—-sfthparallel format -
0x02— v4.0b features (diagonal DC ctx + cross-comp DC)
If you see this error against a v4.0e binary, the file is from a future format generation that hasn't been backported. Open an issue with the first 16 bytes of the file (xxd file.pjg | head -1).
This should never happen. If it does:
-
Verify with
-ver:packJPG a -ver suspect.jpgIf
-verfails, the encoder hit a bug — please open an issue with the source.jpg(or a confidentially-described case). -
Check you're using the same packJPG version for encode and decode. v4.0/v4.0a streams CAN be decoded by later v4.0b+ binaries, but v4.0b+ streams CANNOT be decoded by older builds.
-
Confirm no metadata-stripping flag was used.
-d(discard meta) makes the roundtrip irreversible by design — that's not a bug, but it does mean the output.jpgwill differ from the input.
The Linux release binaries (packJPG_linux_x64) are dynamically linked against libstdc++ and libgcc_s. On distros older than Ubuntu 22.04 / Debian 12 / RHEL 9, the bundled libraries may be too old.
Fix options:
-
Build from source against your local toolchain:
git clone https://github.com/YadeWira/packJPG && cd packJPG/source && make -
Use the
packjpg_<version>_amd64.deborpackjpg-<version>-1.x86_64.rpmfrom the release page — those are tested to install on supported distros.
The default packJPG_win_x64.exe requires Windows 10 or later (uses C++17 <filesystem> and <thread> shipped in modern UCRT).
Fix: download packJPG_win_legacy_x64.exe or packJPG_win_legacy_x86.exe from the release page. These are built from sourcelegacy/ with C++14 + Win32 API in place of <filesystem>, and run on Windows XP through Windows 11.
The .pjg files are 100 % interchangeable between the modern and legacy builds.
The make pgo target needs a workload directory of representative JPEGs. By default it looks at ../test-files/. If that's empty or in a different location:
make pgo PGO_WORKLOAD=/path/to/your/jpgs
Aim for ~10–50 JPEGs of varied sizes and sub-formats (4:4:4, 4:2:0, baseline, progressive). The richer the workload, the better the profile-guided decisions.
-sfth is calibrated for systems with at least 4 logical cores. On dual-core machines, oversubscription costs more than the parallelism wins. For 2-core systems, drop the flag and use the default sequential path. For batch compression, -th2 is the right setting.
Use --no-color to disable color output:
packJPG a --no-color photo.jpg
Or set NO_COLOR=1 in the environment (any non-empty value works) — packJPG respects the NO_COLOR convention.
By default packJPG won't overwrite existing files. To force overwrite, use -o:
packJPG a -o photo.jpg # overwrites photo.pjg if it exists
Or write to a different directory with -od:
packJPG a -od/out photo.jpg # writes /out/photo.pjg
If your problem isn't covered here, open a GitHub issue with:
- packJPG version (banner output)
- OS and architecture (
uname -aon Linux,winveron Windows) - The exact command line you ran
- The full error message
- A sample
.jpgif confidentiality permits, or a description otherwise