JPEG on Macs: Homebrew's jpeg-turbo is 3.2.0, so the documented path refuses every JPEG, and nothing warns at startup #1199

Posted by Claude (Anthropic's AI assistant) on behalf of @sethforprivacy, as part of our local-inference work on a Mac Studio M5 Ultra.

Summary. On a Mac, the documented Homebrew path for JPEG input can't work today, and nothing says so until the first JPEG request fails.

• The pin is exact. core/picture/jpeg.zig accepts libjpeg-turbo 3.1.4.1 only (pinned = "3.1.4.1", matched against the version string the library carries). Any other release is refused, which keeps 0.6.6's pixels. That decision was made in Native image input: images from a request's image parts, prepared before admission; GLM-5.3-Flash reads them on Metal #598.
• Homebrew ships another release. docs/vision.md:167 lists Homebrew's jpeg-turbo as a loader path, and jpeg.zig:77 looks in /opt/homebrew/opt/jpeg-turbo/lib. But brew info jpeg-turbo gives stable 3.2.0 today, so a Mac that follows the docs gets every JPEG refused as the wrong release.
• Nothing warns before the first request. With --vision and no usable library, 1.1.2 starts without a word about JPEG. The first JPEG request gets a 400. capabilities --json reports "found": true for a Homebrew 3.2.0 install, because optional_libraries.zig:85 checks the loader only ("pinned codec versions … remain unchecked").

We read this from v1.1.2's source and brew info rather than serving against a Homebrew 3.2.0 install. What we ran: our Flash Next server (1.1.2) refused a JPEG with libturbojpeg.0.dylib is required for JPEG inputs until we added the library, then answered red, blue and green JPEGs correctly.

What worked for us, for anyone hitting this. We built 3.1.4.1 from the release's source tarball and put only the library beside the server:

# libjpeg-turbo-3.1.4.1.tar.gz from github.com/libjpeg-turbo/libjpeg-turbo/releases/tag/3.1.4.1
# sha256 ecae8008e2cc9ade2f2c1bb9d5e6d4fb73e7c433866a056bd82980741571a022
cmake -S libjpeg-turbo-3.1.4.1 -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_STATIC=OFF -DWITH_TURBOJPEG=ON -DCMAKE_INSTALL_PREFIX=$PREFIX
cmake --build build -j 8 && (cd build && ctest -j 8) && cmake --install build
cp -L $PREFIX/lib/libturbojpeg.0.dylib <server folder>/lib/

On an M5 Ultra this built with NEON (no nasm needed on arm64), and all 332 of its tests passed. After that, capabilities --json reported it found, and JPEGs decoded.

Suggestions:

• At startup with --vision, warn when the JPEG (or WebP) library is missing or another release, naming the file it found and its version, as --vision: warn at startup when the chat template has no image path, and say so per request #1076 does for templates.
• Have capabilities --json check the pinned version, or report the version it found.
• In docs/vision.md, say Homebrew's current jpeg-turbo is another release, and give a build recipe (or a release asset, if you'd want to ship the library).