= Troubleshooting
:experimental:

In case you run into issues here are a few tips that can help you diagnose the
problem.

Generally, it's not a bad idea to configure Emacs to spit the backtrace on error
(instead of just logging the error in the `+*Messages*+` buffer). You can toggle
this behavior by using kbd:[M-x] `toggle-debug-on-error`.

== Debugging CIDER commands

Emacs features a super powerful built-in
http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html[Emacs Lisp debugger]
and using it is the best way to diagnose problems of any kind.

TIP: Here's a https://www.youtube.com/watch?v=odkYXXYOxpo[great crash
 course] on using the debugger.

To debug some command you need to do the following:

* Figure out the name of the command you want to debug (e.g. by using kbd:[C-h k]
to see which command is associated with some keybinding).
* Find the source of the command (e.g. by using kbd:[M-x] `find-function`
kbd:[RET] `function-name`).
* Press kbd:[C-u C-M-x] while in the body of the function
* Run the command again.

At this point you'll be dropped in the debugger and you can step forward until
you find the problem.

== Profiling CIDER commands

Emacs comes with a https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html[built-in
profiler]. Using
it is pretty simple:

. Start it with kbd:[M-x] `profiler-start`.
. Invoke some commands.
. Get the report with kbd:[M-x] `profiler-report`.

TIP: If you intend to share the profiling results with someone it's a good idea to
save the report buffer to a file with kbd:[C-x C-w].

== Debugging the communication with nREPL

From time to time it might be a good idea to inspect the messages exchanged
between CIDER and nREPL. CIDER has a simple message log that looks like this:

  (-->
    id         "16"
    op         "eval"
    session    "eb3ef563-86ec-4d9e-9fa8-a56ce0e0f0b0"
    time-stamp "2020-03-15 16:01:42.963936000"
    code       "(in-ns 'nrepl.completion)"
  )
  (<--
    id         "16"
    session    "eb3ef563-86ec-4d9e-9fa8-a56ce0e0f0b0"
    time-stamp "2020-03-15 16:01:43.027347000"
    ns         "nrepl.completion"
    value      "#namespace[nrepl.completion]"
  )
  (<--
    id         "16"
    session    "eb3ef563-86ec-4d9e-9fa8-a56ce0e0f0b0"
    time-stamp "2020-03-15 16:01:43.195358000"
    status     ("done")
  )

That's CIDER's way of representing the request (marked with `+-->+`) and response maps (marked with `+<--+`).

nREPL message logging is not enabled by default. Set `nrepl-log-messages` to `t`
to activate it. Alternatively you can use kbd:[M-x]
`nrepl-toggle-message-logging` to enable/disable logging temporarily within your
current Emacs session. Note that enabling message logging can impact
performance.

You can find the message log in the `+*nrepl-messages repl-info*+` buffer,
provided you've enabled nREPL message logging. There's going to be one buffer
per each active REPL.

TIP: You can jump quickly to the relevant messages buffer by pressing
kbd:[C-c M-s m].

== Commonly encountered problems (and how to solve them)

=== REPL not starting

Make sure that your CIDER version matches your `cider-nrepl` version. Check
the contents of the `+*Messages*+` buffer for CIDER-related errors. You should
also check the nREPL messages passed between CIDER and nREPL in
`+*nrepl-messages*+`. If you don't see anything useful there it's time to bring
out the big guns.

==== Debugging the REPL init

To debug CIDER's REPL initialization it's a good idea to hook into one of its
entry points. Add a breakpoint to `cider-make-repl` (kbd:[C-u C-M-x], while
in its body). Next time you start CIDER you'll be dropped in the debugger and
you can step forward until you find the problem.

=== Missing `+*nrepl-messages*+` buffer

nREPL message logging is not enabled by default. Set `nrepl-log-messages` to `t`
to activate it. Alternatively you can use kbd:[M-x]
`nrepl-toggle-message-logging` to enable/disable logging temporarily within your
current Emacs session. Note that enabling message logging can impact
performance.

=== `cider-debug` complains that it "`failed to instrument ...`"

In the REPL buffer, issue the following.

 your.namespace> (ns cider.nrepl.middleware.util.instrument)
 cider.nrepl.middleware.util.instrument> (def verbose-debug true)

This will cause CIDER to print extensive information to the REPL buffer when you
try to debug an expression (e.g., with kbd:[C-u C-M-x]). https://github.com/clojure-emacs/cider-nrepl/issues/new[File an issue]
and copy this information.

=== The REPL blows up when some function returns an URL

Most likely you've encountered some issue with the `content-type` middleware. Generally, that's
easy to confirm by inspecting the stacktrace:

[source,clojure]
----
user> (java.net.URI. "mailto:foo@bar.com")
#object[java.net.URI 0x36966ca2 "mailto:foo@bar.com"]ERROR: Unhandled REPL handler exception processing message {:op slurp, :url mailto:foo@bar.com, :session 69c4d8e1-7bb4-45ad-8075-d21995fd50ab, :id 1579}
java.net.UnknownServiceException: protocol doesn't support input
	at java.base/java.net.URLConnection.getInputStream(URLConnection.java:840)
	at cider.nrepl.middleware.slurp$slurp_url_to_content_PLUS_body.invokeStatic(slurp.clj:100)
	at cider.nrepl.middleware.slurp$slurp_url_to_content_PLUS_body.invoke(slurp.clj:82)
	at cider.nrepl.middleware.slurp$handle_slurp.invokeStatic(slurp.clj:117)
	at cider.nrepl.middleware.slurp$handle_slurp.invoke(slurp.clj:109)
----

You can disable the middleware like this:

[source,lisp]
----
(setq cider-repl-use-content-types t)
----

It's disabled by default starting with CIDER 0.25.

=== Debugging freezes & lock-ups

Sometimes a CIDER command might hang for a while (e.g. due to a bug or a
configuration issue). Such problems are super annoying, but are relatively easy
to debug. Here are a few steps you can take in such situations:

* Do kbd:[M-x] `toggle-debug-on-quit`
* Reproduce the problem
* Hit kbd:[C-g] around 10 seconds into the hang

This will bring up a backtrace with the entire function stack, including
function arguments. So you should be able to figure out what's going on (or at
least what's being required).

=== Warning saying you have to use newer nREPL

CIDER currently requires at least nREPL 1.0 to work properly. As nREPL comes
bundled with Leiningen, from time to time you might have to override the
version supplied by them (e.g. if you're forced to use an older version of
Leiningen or there's no release bundling the required nREPL version yet). Leiningen
users can add this to their `profiles.clj` to force the proper dependency:

[source,clojure]
----
{:repl {:dependencies [[nrepl/nrepl "x.y.z"]]}}
----

IMPORTANT: Make sure you add the newer nREPL dependency to the `:dependencies` key instead
of `:plugins` (where the `cider-nrepl` Lein plugin resides). That's a pretty common
mistake.

Generally you're advised to use the newest nREPL with CIDER, as bugs get fixed
in pretty much every release.

=== Missing clojure-... function after CIDER update

Most likely you've updated CIDER, without updating `clojure-mode` as well.

CIDER depends on `clojure-mode` and you should always update them together, as
the latest CIDER version might depend on functionality present only in the latest
`clojure-mode` version.

=== I upgraded CIDER using `package.el` and it broke

The built-in package manager isn't perfect and sometimes it messes up.  If you
just updated and encountered an error you should try the following before
opening an issue: Go into the `.emacs.d/elpa` directory, delete any folders
related to CIDER, restart Emacs and then re-install the missing packages.  Note
that the order here matters.

=== I upgraded CIDER using `package.el` and nothing changed

Emacs doesn't load the new files, it only installs them on disk.  To see the
effect of changes you have to restart Emacs.

=== CIDER complains of the `cider-nrepl` version

This is a warning displayed on the REPL buffer when it starts, and usually looks like this:

____
*WARNING:* CIDER 0.18.0 requires cider-nrepl x.y.z, but you're currently using cider-nrepl a.b.c. Some functionality may not work properly!
____

where `a.b.c` might be an actual version, like `0.17.0`, or it might be `not installed` or `nil`.
The solution to this depends on what you see and on what you're doing.

==== You see a number like `X.X.X`, and you're starting the REPL with `cider-connect`

Your project specifies the wrong version for the cider-nrepl middleware. See the
xref:basics/middleware_setup.adoc[instructions]
in the "Middleware Setup" section.

==== You see `not installed` or `nil`, and you're starting the REPL with `cider-connect`

To use `cider-connect` you need to add the cider-nrepl middleware to your project. See the
xref:basics/middleware_setup.adoc[instructions]
in the "Middleware Setup" section.

==== You see `not installed` or `nil`, and you're starting the REPL with `cider-jack-in`

* Do `C-h v cider-inject-dependencies-at-jack-in`, and check that this variable is non-nil.
* Make sure your project depends on at least Clojure `1.7.0`.
* If you use Leiningen, make sure your `lein --version` is at least `2.9.0`.

If the above doesn't work, you can try specifying the cider-nrepl middleware
manually, as per the
xref:basics/middleware_setup.adoc[instructions]
in the "Middleware Setup" section.

==== You see a number like `X.X.X`, and you're starting the REPL with `cider-jack-in`

This means you're manually adding the cider-nrepl middleware in your project,
but you shouldn't do that because `cider-jack-in` already does that for
you. Look into the following files, and ensure you've removed all references to
`cider-nrepl` and `nrepl`: `project.clj`, `deps.edn`,
`~/.lein/profiles.clj` and `~/.clojure/deps.edn`.

=== I get some error related to refactor-nrepl on startup

The package `clj-refactor` would normally inject its own middleware on
`cider-jack-in`, just as CIDER itself would. Usually that's not a
problem, as long as you're using compatible versions of CIDER and
`clj-refactor`, but if you're getting some error probably that's not
the case. You've got two options to solve this:

* Use compatible versions of the two projects (e.g. their most recent
snapshots or most recent stable releases)
* Disable the `clj-refactor` middleware injection:

[source,lisp]
----
(setq cljr-inject-dependencies-at-jack-in nil)
----

=== Off-by-one column numbers

Emacs and Clojure differ in their indexing of column numbers -- Emacs starts
counting from 0 while Clojure starts from 1. Accordingly, the `cider-nrepl`
middleware uses 1-based indexing and all conversions to 0-based indexing should
be handled client-side. See https://github.com/clojure-emacs/cider/issues/2852.

=== Empty Java stacktraces

Occasionally the JVM might remove some stack frames, resulting in no stacktrace
information being displayed in CIDER's error buffer.

That's caused by a JVM optimization (`OmitStackTraceInFastThrow`, enabled by
default), which optimizes "built-in" exceptions that are thrown frequently enough
to be cached and have no stacktrace.

You can turn off the optimization by adding the JVM flag `-XX:-OmitStackTraceInFastThrow` to whatever
command you're using to start nREPL.

In particular, by adding it to a `deps.edn` file under an alias (eg. `:dev`)
[source,lisp]
---
{:aliases
 {:dev
  {:jvm-opts ["-XX:-OmitStackTraceInFastThrow"]
  ...}}}
---

Or by customising the jack-in options.
[source,lisp]
---
(setq cider-clojure-cli-parameters "-J-XX:-OmitStackTraceInFastThrow")
---

NOTE: Leiningen disables `OmitStackTraceInFastThrow` by default.

=== Navigation to JDK sources doesn't work

If you try to navigate to the sources of third-party Java libraries, make sure
that the variable `cider-download-java-sources` is set to `t`.

If you are on Linux and still can't navigate to the source of built-in methods like `.toUpperCase` you
probably haven't installed the JDK sources. On Debian/Ubuntu:

[source,shell]
----
$ sudo apt install openjdk-21-source openjdk-21-doc
----

On Red Hat/Fedora/CentOS:

[source,shell]
----
$ sudo dnf install java-21-openjdk-src java-21-openjdk-javadoc
----

On Guix:

[source,shell]
----
$ guix package -i openjdk:jdk
----

NOTE: On Windows and macOS the JDK source code is bundled with the JDK.

=== Pressing `RET` in the REPL does not evaluate forms

Are you a Paredit user? Have you enabled for the REPL buffers?

In recent versions of Paredit (25+), `RET` is bound to `paredit-RET`. This can cause unexpected
behavior in the repl when `paredit-mode` is enabled, e.g. it appears to hang after hitting
`RET` instead of evaluating the last form.

You can disable this Paredit behavior by adding the following to your `init.el`:

[source,lisp]
----
(define-key paredit-mode-map (kbd "RET") nil)
----

=== Interactions fail with `No linked CIDER sessions`

If any interactive feature is being shortcircuited for you with the message `No linked CIDER sessions`,
that's due to one of the following reasons:

* You're evaluating code in a buffer from a project that hasn't started a repl
 ** You can fix this by switching instead to a project that has.
 ** You can also, simply, start a repl in the current project.
* There's a bug in the CIDER/Sesman integration
 ** Session linking generally works by determining whether the current buffer is related to the classpath of some REPL.
 ** You can obtain debug info echoed to the `+*Messages*+` buffer by running `M-x cider-debug-sesman-friendly-session-p` on the problematic buffer.
  *** By reading it, you might be able to determine why CIDER failed to see the relationship between `(buffer-filename)` and the classpath.
  *** Feel free to create a detailed GitHub issue including this information.
