Troubleshooting the REPLλ︎
The aspects to consider when a REPL process fails to run are:
- Some code expressions are not correct
- Dependencies are not available
- Project (or editor) misconfigured
Code expression failingλ︎
All code in the project must compile and be syntactically correct, even if that code is in a rich
(comment ,,,) block.
A Clojure expression following a Reader comment,
#_ does not have to compile, however it must be syntactically correct, i.e. balanced parentheses.
Add a line comment,
;;, to any code that is suspected of not compiling or being syntactically incorrect (or delete that code).
Editor REPL fails to startλ︎
If using a jack-in approach with the editor to start the repl, run a terminal UI REPL with an nREPL server and try connecting to that REPL from the editor.
Then require the main namespace and see if there are issues, optionally using :verbose to see which libraries are being loaded.
If the REPL runs correctly, it is likely the editor configuration is missing something or is incorrect. Check the configuration for running a Clojure project with the editor.
Terminal UI REPL fails in projectλ︎
If the REPL does not run correctly or the namespace fails to load, run a repl without any extra development dependencies (tooling, dev libraries, etc) and load the main namespace
REPL doesnt start in any projectλ︎
clojure command in a directory that is not part of any existing Clojure project. This will run the REPL with only the
clojure -Sdescribe to check that the Clojure CLI is using the correct configuration files and is the expected version.
If a REPL prompt appears, then Clojure CLI is working. If a REPL prompt does not appear, then reinstall the Clojure CLI or upgrade to a newer version.
REPL starts but requiring code failsλ︎
Creating a new project is a fast way to check development tooling is working correctly. A project can be created with
clojure -T:project/create (with Practicalli Clojure CLI Config installed)
If a REPL process starts correctly for a new project but not the existing project, then its most likely one or more expressions in the existing project that are causing an error or the project
deps.edn configuration from the existing project to the root of the new project (or just the
:deps section of the
deps.edn configuration). Run the REPL again using the
clojure command. If the REPL fails then it is likely an issue with the exiting projects
deps.edn file or one of the dependencies
Projects typically depend on many other libraries and sometimes those libraries depend on other libraries too.
When running the
clojure command to run a terminal UI REPL, libraries are retrieved from remote repositories (Maven Central, Clojars.org) and stored in a local cache
If a dependency is not available then a warning should state which library cannot be downloaded and from which repository
Check the extent of the dependencies for the existing project:
Use the antq tool to check for a newer version of a dependency
If libraries are likely to become unavailable (i.e. old versions) then consider creating a local repository service with Artefactory or Nexus, which can share library depenencies between development teams of an organisation.