Debug missing libraries, version conflicts, classpath surprises, cached dependency failures, and Maven/Clojars access problems in Clojure CLI and Leiningen projects.
Clojure dependency failures are usually JVM dependency failures with Clojure-shaped configuration. The library still resolves from Maven repositories, the runtime still gets a classpath, and transitive dependencies can still choose versions you did not expect. Your Java dependency-management instincts transfer, but the diagnostic commands are different.
Start by identifying the tool that owns the classpath: Clojure CLI with deps.edn, Leiningen with project.clj, Maven, or Gradle.
| Symptom | First diagnosis |
|---|---|
Could not find artifact ... |
Wrong coordinates, unavailable repository, proxy/TLS issue, or typo. |
ClassNotFoundException |
Dependency not on the active classpath or wrong artifact selected. |
NoSuchMethodError |
Runtime version conflict: a different library version loaded than the code expects. |
| Namespace cannot be located | Source path, dependency classpath, or namespace-to-file mapping problem. |
| Works with one alias but not another | Alias changes :extra-deps, :extra-paths, or JVM options. |
Do not solve every dependency problem by deleting ~/.m2/repository. That is the last step after you know the coordinate and classpath are correct.
For deps.edn projects, inspect the computed classpath and dependency tree:
1clojure -Spath
2clojure -Stree
3clojure -Sverbose -Spath
4clojure -Srepro -Stree
Use -Srepro when you suspect user-level deps.edn is changing the result. It omits user configuration so you can see whether the project is reproducible for teammates and CI.
For newer dependency reporting, the built-in :deps tools are often useful:
1clojure -X:deps tree
2clojure -X:deps list
Use the exact aliases your failing command uses:
1clojure -A:test -Spath
2clojure -A:test -Stree
If the failure only happens under :test, debug the :test alias instead of the base project.
deps.edn Issues| Need | deps.edn tool |
|---|---|
| Add a test-only library | :extra-deps under a test alias. |
| Add a test source path | :extra-paths under a test alias. |
| Force a selected dependency version | :override-deps. |
| Use a different local Maven cache | :mvn/local-repo. |
| Add a repository mirror | Top-level :mvn/repos. |
Example:
1{:paths ["src" "resources"]
2 :deps {org.clojure/clojure {:mvn/version "1.12.5"}}
3 :aliases
4 {:test
5 {:extra-paths ["test"]
6 :extra-deps {io.github.cognitect-labs/test-runner
7 {:git/tag "v0.5.1"
8 :git/sha "dfb30dd"}}}}}
The dependency is not globally added. It is added only when the :test alias participates in the command.
For project.clj projects, use Leiningen’s dependency tree:
1lein deps :tree
2lein classpath
3lein test
Leiningen exclusions live on dependency vectors:
1:dependencies [[ring/ring-core "1.12.2" :exclusions [commons-codec/commons-codec]]
2 [commons-codec/commons-codec "1.17.1"]]
Do not add exclusions mechanically. First confirm which transitive dependency is actually selected and which API your code or library expects.
| Problem | Better diagnostic |
|---|---|
| Corporate proxy blocks Maven Central | Check proxy variables, Maven settings, and Clojure CLI repository config. |
| One dependency appears corrupted | Delete that artifact folder under ~/.m2/repository, not the entire cache. |
| CI cannot download private artifacts | Check credentials, repository URL, and secret availability in CI. |
| Local machine works but teammate fails | Run with -Srepro and compare project config, not user config. |
| Transitive version differs from expectation | Use -Stree, -X:deps tree, or lein deps :tree. |
clojure -Sforce can mark a cached classpath stale and force recomputation. Use it when the classpath cache is suspicious; it is not a fix for wrong dependency coordinates.
| Java/Maven instinct | Clojure equivalent |
|---|---|
Inspect dependency:tree |
Use clojure -Stree, clojure -X:deps tree, or lein deps :tree. |
| Check effective POM or Gradle configurations | Check merged aliases and -Srepro behavior. |
| Use dependency management to pin versions | Use :override-deps, direct deps, or Lein exclusions plus explicit dependency. |
| Separate test dependencies | Use test aliases or Lein profiles. |
| Verify final classpath | Use clojure -Spath, lein classpath, Maven, or Gradle classpath tasks. |
The key shift is that deps.edn is data that constructs a classpath. If the classpath is wrong, inspect the data sources and aliases used to produce it.