Resolving ClassNotFoundException in Ceylon JVM Deployments

The Problem: Missing Runtime Dependencies

When executing a Ceylon program compiled for the Java Virtual Machine (JVM), you may encounter a ClassNotFoundException or NoClassDefFoundError. This typically occurs when the JVM attempts to instantiate core Ceylon types—such as Ceylon::List or Ceylon::String—but cannot find the necessary supporting logic in the runtime environment.

The core cause is that the Ceylon compiler transforms .ceylon source files into standard .class bytecode, but it does not embed the Ceylon runtime library into your application's output JAR. The runtime must be explicitly provided at execution time.

Diagnostic Matrix

Step-by-Step Resolution Path

1. Verify Runtime Presence

If you are manually invoking the JVM, ensure the ceylon-runtime.jar is explicitly included. Run the following command from your terminal to see exactly where the JVM is attempting to load classes from:

# Run with verbose class loading enabled
java -verbose:class -cp "your-app.jar:path/to/ceylon-runtime.jar" com.example.Main

Expected Result: You should see a line indicating that ceylon.runtime.xxx is being loaded from the ceylon-runtime.jar file. If the output shows a failure to locate the class before the crash, the path to the runtime JAR is incorrect.

2. Validate Version Alignment

Ceylon is sensitive to version mismatches between the compiler used to generate the bytecode and the runtime library used to execute it. Mixing versions often results in NoSuchMethodError or linkage errors.

• Check the compiler version: ceylon-compiler --version
• Check the runtime JAR version: Inspect the filename or the MANIFEST.MF inside the ceylon-runtime.jar.

If these versions do not match exactly, replace the runtime JAR with the version corresponding to your compiler.

3. Test with the Ceylon Toolchain

To determine if the issue is a configuration error in your deployment pipeline or a fundamental code issue, bypass manual classpath management using the ceylon-run utility:

# Run the module directly through the toolchain
ceylon-run your.module.name

If the program executes successfully here, the issue is confirmed to be a missing or misconfigured classpath in your java execution command.

Correcting the Execution Command

To move from a failing manual execution to a successful one, ensure your classpath (-cp) includes both your compiled classes and the runtime library. Use the appropriate separator for your OS (: for Unix/Linux, ; for Windows).

# Example for Linux/macOS
java -cp "bin/app.jar:lib/ceylon-runtime.jar" com.example.Main

Risk: Do not bundle the runtime library into a "fat JAR" without verifying that the Main-Class attribute in the manifest is correctly pointing to the entry point, as Ceylon's module system may expect specific directory structures.

Limitations and Compatibility

Ceylon is a dormant project. Its toolchain and runtime libraries were designed for older JDKs. If you are using JDK 17 or newer, you may encounter InaccessibleObjectException due to strong encapsulation of JDK internals. In such cases, you may need to add --add-opens flags to your JVM command to allow the Ceylon runtime to access internal Java APIs.

Rollback Procedure

If adding a new runtime JAR causes new LinkageError exceptions, remove the added JAR from the classpath and revert to the previous version of ceylon-runtime.jar that matched your original build environment.