metadata.config exceeds Hex 2.4.2's 128KB limit — breaks cold installs

[crayment]

metadata.config exceeds Hex 2.4.2's 128KB limit — breaks cold installs

kaffy 0.10.3 and 0.11.0 both fail to install under Hex 2.4.2+.

What happens

** (Mix) Unpacking tarball failed: file too big: metadata.config

mix deps.get fails when unpacking the kaffy tarball into deps/. It only occurs on a cold install (no existing deps/kaffy directory) — projects with a warm cache are unaffected until the cache is cleared or a fresh environment is used.

How to reproduce

rm -rf deps/kaffy
mix local.hex --force  # ensure Hex 2.4.2+
mix deps.get
# => ** (Mix) Unpacking tarball failed: file too big: metadata.config

Or directly via erl:

curl -s https://repo.hex.pm/tarballs/kaffy-0.10.3.tar -o kaffy-0.10.3.tar
erl -noshell \
  -pa ~/.mix/archives/hex-2.4.2-otp-27/hex-2.4.2-otp-27/ebin \
  -eval '
    {ok, T} = file:read_file("kaffy-0.10.3.tar"),
    {error, R} = mix_hex_tarball:unpack(T, "/tmp/dest", mix_hex_core:default_config()),
    io:format("~s~n", [mix_hex_tarball:format_error(R)]),
    halt().'
# => file too big: metadata.config

Root cause

Hex 2.4.2 (released April 30, 2026) vendors hex_core v0.15.0, which introduced a hard limit of 128KB (131,072 bytes) on the metadata.config file inside Hex package tarballs. The limit was added in hex_core PR #166 as protection against malformed packages, and applies during both package creation and extraction.

kaffy's metadata.config is 134,680 bytes — 3,608 bytes over the limit. The likely cause is the package's large files list in its metadata: kaffy bundles 1,840 static asset files (CKEditor, FontAwesome fonts/SVGs, etc.) and all their paths appear in metadata.config.

Both 0.10.3 and 0.11.0 are affected (0.11.0 is 134,692 bytes).

curl -s https://repo.hex.pm/tarballs/kaffy-0.10.3.tar | tar xOf - metadata.config | wc -c
# => 134680  (limit is 131072)

Fix

A new release with a metadata.config under 131,072 bytes would fix this. The most direct approach is adding a .hex_include or trimming the files list in mix.exs to exclude large static assets from the published package metadata. Alternatively, restructuring to not include all asset paths in the package manifest would bring it under the limit.

References

• hex_core PR that introduced the limit: Add file-based unpack and size validations for tarball files hexpm/hex_core#166
• Hex 2.4.2 release: https://hex.pm/packages/hex/2.4.2
• MAX_METADATA_SIZE definition: hex_core/src/hex_tarball.erl:19

[eriknaslund]

I ran into the same problem, and the workaround I had to use for now was to include Kaffy via git, like this:

{:kaffy, git: "https://github.com/aesmail/kaffy", ref: "b31b54eac985aec644d48440bd96da74341f8974"},

It's very much a hack, but it works since the mix_hex_tarball:unpack doesn't get used this way.

[eriknaslund]

Sadly, for me it made more sense to move away from Kaffy, which I did a few days ago. I felt there were too many outstanding issues not being addressed and I was already running my own fork for some fixes I needed. This is in no way any criticism against the maintainers, because I know it takes a lot of time to maintain these things...I've had great use of Kaffy over the years, so thanks a bunch for that! :).

[sigu]

@eriknaslund what are you using in place of Kaffy?

[eriknaslund]

@sigu I ended up switching to Backpex. It's only been about 2 weeks since the switch, but so far it's been great.