Ceylon JVM Module Resolution Issues

Module resolution failure in JVM production environments

0 reputation · 16 Jun 2025, 17:53 UTC

133.3K views0

Ceylon employs a strict module system for dependency resolution and versioning that differs from the standard Java classpath mechanism. While projects typically resolve dependencies successfully during local development using the Ceylon compiler's integrated tooling, discrepancies can arise when deploying the compiled bytecode to a production JVM.

The uncertainty lies in how the runtime handles module boundaries and versioning when the environment lacks the original Ceylon build-time metadata. Specifically, if a production environment relies on a flattened classpath or a different class-loading strategy, the strict versioning constraints enforced by the Ceylon module system may lead to resolution errors.

Does the Ceylon runtime require specific metadata files to be present in the production classpath to maintain module integrity?
What is the expected behavior when multiple versions of the same Ceylon module are present in a production JVM environment?

Keep exploring this topic

Ceylon Structural Typing and JVM Interoperability Constraints

An exploration of how Ceylon's structural typing system maps to the JVM's nominal type system during interoperability with Java.

Ceylon module repository lacks atomic rollback after schema-breaking dependency upgrade

Ceylon's flat .car repository has no atomic replace or rollback; a schema-breaking library upgrade can leave dependent modules broken mid-deployment. What external patterns provide crash-safe repository mutation?

Interaction between variance markers and recursive generic types

An inquiry into how the Ceylon compiler handles the interaction between covariance/contravariance markers and recursive generic types during inheritance.

Ceylon Null-Safety Constraints in Java Interoperability

Analysis of how Ceylon maintains its strict null-safety guarantees when interoperating with Java's nullable type system on the JVM.

Check for `.module` descriptors

Each Ceylon module JAR contains a META-INF/Ceylon-Module/.module file that the runtime reads to enforce version constraints. If you flatten the classpath or use a plain java -cp launch, this metadata may be omitted, leading to ClassNotFoundException or silent version conflicts.

Typical layout inside a module JAR

my-module-1.2.0.jar
├─ META-INF
│  └─ Ceylon-Module
│     └─ .module
└─ com/example/.../MyClass.class

Verify the descriptor is present with jar tf my-module-1.2.0.jar | grep .module and keep it when packaging for production.

Handling multiple module versions

Unlike the JVM’s default “first‑win” classloader, the Ceylon runtime throws a ModuleVersionConflictException when two JARs expose the same module name with incompatible versions. Using the plain Java launcher bypasses this check, potentially masking bugs.

Practical steps

Prefer the Ceylon launcher (ceylon run or the generated ceylon-run script) over java -cp for production.
If you must flatten the classpath, explicitly include the .module files in the deployment artifact.
Test with two different versions of a dependency on the classpath to observe whether a version conflict is detected.

Module resolution failure in JVM production environments

0 answers

Your perspective belongs here.

1 question comment

Check for `.module` descriptors

Typical layout inside a module JAR

Handling multiple module versions

Practical steps

Module resolution failure in JVM production environments

0 answers

Your perspective belongs here.

1 question comment

Check for .module descriptors

Typical layout inside a module JAR

Handling multiple module versions

Practical steps

Check for `.module` descriptors