Diagnosing & Fixing Ceylon Module Resolution Errors

Recognizable Condition

During a Ceylon build you see messages like:

Ceylon: Error: cannot resolve module "org.example.foo" 1.2.0
Ceylon: Error: cannot resolve module "org.example.bar" 2.0.0

or the compiler aborts with a stack trace that references missing module descriptors. These symptoms mean the compiler cannot locate the required module on the module path or the descriptor is invalid.

Cause & Diagnostic Table

Symptom	Likely Cause	Diagnostic Hint
"cannot resolve module" error	module descriptor missing or malformed	Check that module.ceylon exists and is syntactically correct.
Compiler aborts with "module not found"	module version mismatch	Verify the version in module.ceylon matches the artifact on the module path.
Missing dependency listed in module.ceylon	module path point wrong directory	Run ceylon compile --module-path and list modules to confirm presence.
Exported API not visible in dependent module	export clause missing	Inspect the dependent module’s module.ceylon for exports.
Syntax or semantic errors on older compiler	compiler version too old for module syntax	Confirm compiler version with ceylon --version and compare to module’s language level.
Unable to load jar despite correct path	jar corrupted or renamed	Check file hash and name on disk.

Ordered Checks

1. Verify Module Descriptor
   Locate module.ceylon in the source root. It should look like:

   module org.example.foo 1.2.0 {
       import org.example.bar 2.0.0;
   }
   

   Check for syntax errors (missing braces, wrong quotes) using a Ceylon-aware editor or ceylon compile --check-module.
2. Confirm Module Path
   Run:

   ceylon compile --module-path ./modules --list-modules
   

   This lists all modules the compiler sees. If your target module is missing, the path is wrong or the jar isn’t in the directory.
3. Match Versions
   Open the jar’s META-INF/ceylon/module.ceylon (or the source module.ceylon) and ensure the version matches the one declared in your project’s module.ceylon. A mismatch triggers a resolution error.
4. Check Export Clauses
   If a consumer cannot access a public type, the provider’s module.ceylon must export the package:

   module org.example.bar 2.0.0 {
       exports org.example.bar.internal;
   }
   

5. Validate Compiler Compatibility
   Run ceylon --version. If the module uses language features introduced in Ceylon 1.3.x, ensure you’re using a compiler that supports it.
6. Inspect Artifact Integrity
   Verify the jar’s checksum or re‑download it if you suspect corruption.
7. Re‑run Tests
   After any change, execute ceylon test to confirm the module compiles and tests run.

Fixes Tied to Findings

• Missing module.ceylon: Create or restore the file. Use a backup if available.
• Malformed descriptor: Correct syntax errors or regenerate from a template.
• Version mismatch: Update the module.ceylon version or replace the jar with the matching version.
• Wrong module path: Adjust the --module-path argument or move the jar into the correct directory.
• Missing export: Add the appropriate exports clause to the provider’s descriptor.
• Outdated compiler: Upgrade to a newer Ceylon release or downgrade the module’s language level.
• Corrupted jar: Re‑download the artifact from a trusted repository.

Escalation Criteria

If, after following the above steps, the build still fails:

• The error message includes a stack trace that references internal Ceylon compiler classes—this may indicate a bug in the compiler itself.
• You’re using a module that has been published with an incorrect descriptor (e.g., missing exports), and no upstream fix is available.
• Multiple modules across the project are unresolved despite identical module paths and versions.

At this point, file a bug against the Ceylon project or seek help on the community mailing list. Include the exact compiler output, the relevant module.ceylon contents, and the module path layout.

Limitations & Practical Check

• Ceylon is no longer actively maintained; newer projects may migrate to Kotlin or the Java module system.
• Always back up module.ceylon before editing to avoid cascading errors.
• After any fix, run ceylon compile --module-path ./modules and verify that the compiler lists the affected module without errors.