Diagnosing Ceylon Module Dependency Resolution Failures

Recognizable condition

When a Ceylon build fails, the compiler often emits messages such as error: module X not found, error: conflicting versions, or a stack trace indicating a cyclic dependency. These symptoms point to problems in the module resolution phase rather than plain Java compilation errors.

Cause and diagnostic table

Condition	Typical symptom	Likely cause
Module import unresolved	error: module <name> not found	Missing module in repository, incorrect module name, or absent module.ceylon descriptor
Version conflict	error: conflicting versions for the same library	Two modules depend on different versions of a shared dependency
Missing module descriptor	Build treats a JAR as a plain Java library; Ceylon‑specific checks are skipped	JAR lacks a module.ceylon file in its root
Circular dependency	Stack overflow or error: cyclic dependency during resolution	Module A imports B and B imports A (directly or transitively)
Incompatible JVM version	UnsupportedClassVersionError at runtime	Modules compiled with a newer language level than the target JVM supports

Ordered checks

1. Run the build with verbose logging to locate the exact point of failure:

   ceylon compile --verbose

   Look for lines that mention Resolving module or Loading module descriptor.

2. Verify the JVM version meets the Ceylon toolchain requirement (Java 8 or newer):

   java -version

3. Inspect each source directory for a module.ceylon file and confirm its import statements:

   find . -name 'module.ceylon' -exec cat {} \;

4. Check the module repository (default ~/.ceylon/repo) for the missing module or its expected version:

   ls ~/.ceylon/repo/org/example/<module-name>/

5. If a JAR is being used as a dependency, verify it contains a module.ceylon entry:

   jar -tf path/to/dependency.jar | grep module.ceylon

Fixes tied to findings

1. Missing or misnamed module

• Ensure the module name in module.ceylon matches the directory structure (org/example/myapp → module name org.example.myapp).
• If the module is not published, run ceylon compile on its source first, then ceylon republish to make it available in the local repo.
• Correct any typo in the import statement (e.g., import org.example.foo "1.0.0").

2. Version conflict

• Run ceylon doc --module <module-name> for each conflicting module to see the version constraints they declare.
• Align the constraints: either upgrade/downgrade one side to use a compatible version, or use a version range that satisfies both (e.g., "1.2.0" -< "2.0.0").
• After editing module.ceylon, run ceylon compile --verbose again to confirm the conflict disappears.

3. Missing module descriptor in a JAR

• Obtain the source of the library and add a proper module.ceylon file at the root of the JAR.
• If you cannot modify the library, wrap it in a Ceylon module that merely re‑exports its packages:

module org.example.wrapper "1.0.0" {
    import java.base "8";
    shared import java.util "1.8";
}

• Place the wrapper module in your local repository and depend on it instead of the raw JAR.

4. Circular dependency

• Use the dependency graph output from verbose mode to identify the cycle (e.g., A → B → A).
• Refactor: move shared code to a third module C and have both A and B import C instead of each other.
• If a true circular relationship is required, consider merging the modules or using an interface‑only module to break the cycle.

5. Incompatible JVM version

• Check the language level used during compilation (look for source compatibility in the build script).
• Either upgrade the target JVM to meet the required level (java -version ≥ required) or downgrade the Ceylon source compatibility by setting --source 1.8 (or appropriate) in ceylon compile.
• Re‑compile all modules after changing the JVM or source level.

Escalation criteria

• If after verifying the module descriptor and versions the error persists, check for corrupted repository artifacts (rm -rf ~/.ceylon/repo/org/example/<module>) and republish.
• When the build fails with a stack overflow that does not map to a clear import cycle, enable -Xss to increase stack size temporarily and re‑run to confirm it’s a genuine cycle.
• If the JVM version check passes but UnsupportedClassVersionError still appears, verify that the ceylon executable you are invoking is using the intended java on $PATH (use which java or the full path).
• When multiple modules exhibit the same resolution failure despite correct descriptors, suspect a misconfigured repository URL (check ~/.ceylon/config or the --rep flag).

Verification

1. After applying a fix, run ceylon compile without --verbose and ensure the build completes with exit code 0.
2. Optionally, run ceylon test or execute the resulting artifact to confirm runtime correctness.
3. Check that no new error: lines appear in the output.

Limitations

• Verbose output can be lengthy; filtering with grep for Resolving or error: helps isolate relevant lines.
• The local repository may contain stale versions; periodically clean ~/.ceylon/repo if you suspect version skew.
• Some third‑party JARs lack source, making descriptor addition impossible; the wrapper approach described above is the only viable workaround.

Rollback (if you edited module.ceylon)

If you modified a module.ceylon file and need to revert, restore the backup you created before editing:

cp module.ceylon.bak module.ceylon

Then re‑run the build to confirm the original state.