Skip to content

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.

Clojure CLI repl - rebel terminal UI

clojure -M:repl/rebel

Then require the main namespace and see if there are issues, optionally using :verbose to see which libraries are being loaded.

(require '[practicalli.service] :verbose)

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λ︎

Run the clojure command in a directory that is not part of any existing Clojure project. This will run the REPL with only the org.clojure/clojure dependency

Run 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.

Clojure CLI install - Practicalli Guide

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.

Copy the 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

Dependency issuesλ︎

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, and stored in a local cache ~/.m2/repositories

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:

clojure -Stree

Use the antq tool to check for a newer version of a dependency

clojure -T:project/outdated

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.

Last update: January 28, 2023