Making it clear why a version-mismatched escript could not be run

LeonardB · May 13, 2026, 4:53pm

It seems to be version dependent.

Compiled with 29, run with 26

=ERROR REPORT==== 13-May-2026::12:52:14.876489 ===
beam/beam_load.c(150): Error loading module etest:
  corrupt atom table


escript: exception error: undefined function etest:main/1
  in function  escript:run/2 (escript.erl, line 750)
  in call from escript:start/1 (escript.erl, line 277)
  in call from init:start_em/1 
  in call from init:do_boot/3

garazdawi · May 13, 2026, 6:25pm

It depends on what the incompatibility is. The opcode incompatibility happens often enough that we have made the error message better. It is also easy to detect as we never re-use old opcodes so new ones will always be higher. The corrupt atom table has only happened once, so normally the error would mean exactly what it says, that the atom table is corrupt for some reason.

Maybe a better approach would be to embed the version used to compile in the .beam file, and then if it fails to load suggest that maybe the issue is that the beam file is compiled with a too modern compiler. There is already some metadata in the .beam file, it could be that the only thing we need is to extract that when loading to make the error messages nicer.

bjorng · May 14, 2026, 2:35am

The reason for the seemlingly corrupt atom table is this pull request for Erlang/OTP 28:

github.com/erlang/otp

compiler: Support long UTF-8 encoded atoms (#8913)

master ← bjorng:bjorn/long-utf8-atoms/OTP-19285

opened 07:07AM - 08 Oct 24 UTC

bjorng

+90 -22

Support for atoms containing any Unicode code point was added in Erlang/OTP 20 (…#1078). After that change, an atom can contain up to 255 Unicode code points. However, atoms used in Erlang source code is still limited to 255 bytes because the atom table in the BEAM file only has a byte for holding the length in bytes of the atom text. For instance, the `🟦` character has a four-byte encoding (`<<240,159,159,166>>`), meaning that Erlang source code containing a literal atom consisting of 64 or more such characters cannot be compiled. This pull request changes the atom table in BEAM files to use ~two bytes~ a variable length encoding for the length of each atom. For atoms up to 15 bytes, the length is encoded in one byte. The header for the atom table is also changed to indicate that ~two-byte length~ the new encodiging of lengths are used. Attempting to load a BEAM file compiled with Erlang/OTP 28 in Erlang/OTP 27 or earlier will result in the following error message: 1> l(t). =ERROR REPORT==== 8-Oct-2024::08:49:01.750424 === beam/beam_load.c(150): Error loading module t: corrupt atom table {error,badfile} `beam_lib` is updated to handle the new format. External tools that use `beam_lib:chunks(Beam, [atoms])` to read the atom table will continue to work. External tools that do their own parsing of the atom table will need to be updated.

It is unfortunate that we had to fix the length limitation of UTF-8 encoded atoms in this way, but it is extremely unlikely that we will have to do something similar again. So when loading future BEAM files in OTP 28 and later, the nicer message should always be shown. For example, attempting to load a BEAM file using native records in OTP 28 will show this message:

1> l(t).
=ERROR REPORT==== 14-May-2026::03:36:31.420679 ===
beam/beam_load.c(194): Error loading module t:
  This BEAM file was compiled for a later version of the runtime system than the current (Erlang/OTP 28).
  To fix this, please re-compile this module with an Erlang/OTP 28 compiler or update your Erlang/OTP version.
  (Use of opcode 189; this emulator supports only up to 184.)


{error,badfile}

lpil · May 14, 2026, 10:39am

That’s great to hear! Thank you.

Perhaps in an ideal world the programmer could supply a custom message, to help users know how to upgrade, but I am quite satisfied with this output as it is.