Unresolved references are not supported: Gleam module imports in low-traffic deployments

Answer

The question asks for a safe way to confirm that a trimmed import graph in a Gleam project remains correct across compiler versions, and whether the compiler’s unresolved‑reference error guarantees that all transitive dependencies are present in the generated BEAM code. The answer is split into three parts:

1. What the compiler guarantees

• The Gleam compiler performs a static walk of all imports that are reachable from the compiled entry points. If any referenced module cannot be found, it aborts the build with an Unresolved references are not supported error.
• Because Gleam has no lazy or deferred loading, every module that the compiler can reach is emitted as Erlang code in the final artifact. Pruning imports only removes source references; the Erlang code for a module that is still reachable remains in the artifact.
• The unresolved‑reference check covers direct and transitive imports that are statically visible in the source. It does not detect missing modules that are loaded at runtime via Erlang primitives such as :code.load_file/1 or :code.ensure_loaded/1.

2. Practical verification steps

1. Run gleam build after any change to the import graph. Treat any unresolved‑reference error as a hard failure; do not proceed to packaging or deployment.
2. Pin the Gleam compiler version in CI (e.g., by locking the gleam dependency in gleam.toml). Re‑run the above build after each compiler upgrade to catch regressions in resolution behaviour.
3. After a successful build, inspect the _build/*/lib/your_app/ebin directory. All modules that the runtime will touch should have a corresponding .beam file. If a module is referenced in the generated Erlang but missing from ebin, the build would have failed, so this step mainly serves as a sanity audit.
4. Run the full test suite in a staging BEAM node that mirrors production. This exercises every code path and will surface runtime undef or module_not_found errors that the compiler could not detect.
5. If the application performs dynamic loading of Erlang modules (for example, via :code.load_file/1 or loading third‑party libraries that are not statically imported), add an explicit startup check that attempts to load each such module and aborts with a clear error if any are missing.

3. When the compiler’s check is insufficient

Only when dynamic loading is present does the unresolved‑reference check fail to guarantee runtime safety. In that case the additional startup verification (step 5) becomes mandatory.

Missing diagnostic detail that could change the recommendation

Does your application use any dynamic Erlang module loading or external libraries that are not referenced directly in the Gleam source? If the answer is yes, the runtime check described above is required; if not, the build‑time unresolved‑reference error and the full test suite are sufficient.