1= Troubleshooting 2:experimental: 3 4In case you run into issues here are a few tips that can help you diagnose the 5problem. 6 7Generally, it's not a bad idea to configure Emacs to spit the backtrace on error 8(instead of just logging the error in the `+*Messages*+` buffer). You can toggle 9this behavior by using kbd:[M-x] `toggle-debug-on-error`. 10 11== Debugging CIDER commands 12 13Emacs features a super powerful built-in 14http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html[Emacs Lisp debugger] 15and using it is the best way to diagnose problems of any kind. 16 17TIP: Here's a https://www.youtube.com/watch?v=odkYXXYOxpo[great crash 18 course] on using the debugger. 19 20To debug some command you need to do the following: 21 22* Figure out the name of the command you want to debug (e.g. by using kbd:[C-h k] 23to see which command is associated with some keybinding). 24* Find the source of the command (e.g. by using kbd:[M-x] `find-function` 25kbd:[RET] `function-name`). 26* Press kbd:[C-u C-M-x] while in the body of the function 27* Run the command again. 28 29At this point you'll be dropped in the debugger and you can step forward until 30you find the problem. 31 32== Profiling CIDER commands 33 34Emacs comes with a https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html[built-in 35profiler]. Using 36it is pretty simple: 37 38. Start it with kbd:[M-x] `profiler-start`. 39. Invoke some commands. 40. Get the report with kbd:[M-x] `profiler-report`. 41 42TIP: If you intend to share the profiling results with someone it's a good idea to 43save the report buffer to a file with kbd:[C-x C-w]. 44 45== Debugging the communication with nREPL 46 47From time to time it might be a good idea to inspect the messages exchanged 48between CIDER and nREPL. CIDER has a simple message log that looks like this: 49 50 (--> 51 id "16" 52 op "eval" 53 session "eb3ef563-86ec-4d9e-9fa8-a56ce0e0f0b0" 54 time-stamp "2020-03-15 16:01:42.963936000" 55 code "(in-ns 'nrepl.completion)" 56 ) 57 (<-- 58 id "16" 59 session "eb3ef563-86ec-4d9e-9fa8-a56ce0e0f0b0" 60 time-stamp "2020-03-15 16:01:43.027347000" 61 ns "nrepl.completion" 62 value "#namespace[nrepl.completion]" 63 ) 64 (<-- 65 id "16" 66 session "eb3ef563-86ec-4d9e-9fa8-a56ce0e0f0b0" 67 time-stamp "2020-03-15 16:01:43.195358000" 68 status ("done") 69 ) 70 71That's CIDER's way of representing the request (marked with `-->`) and response maps (marked with `<--`). 72 73nREPL message logging is not enabled by default. Set `nrepl-log-messages` to `t` 74to activate it. Alternatively you can use kbd:[M-x] 75`nrepl-toggle-message-logging` to enable/disable logging temporary within your 76current Emacs session. Note that enabling message logging can impact 77performance. 78 79You can find the message log in the `+*nrepl-messages repl-info*+` buffer, 80provided you've enabled nREPL message logging. There's going to be one buffer 81per each active REPL. 82 83TIP: You can jump quickly to the relevant messages buffer by pressing 84kbd:[C-c M-s m]. 85 86== Commonly encountered problems (and how to solve them) 87 88=== REPL not starting 89 90Make sure that your CIDER version matches your `cider-nrepl` version. Check 91the contents of the `+*Messages*+` buffer for CIDER-related errors. You should 92also check the nREPL messages passed between CIDER and nREPL in 93`+*nrepl-messages*+`. If you don't see anything useful there it's time to bring 94out the big guns. 95 96==== Debugging the REPL init 97 98To debug CIDER's REPL initialization it's a good idea to hook into one of its 99entry points. Add a breakpoint to `cider-make-repl` (kbd:[C-u C-M-x], while 100in its body). Next time you start CIDER you'll be dropped in the debugger and 101you can step forward until you find the problem. 102 103=== Missing `+*nrepl-messages*+` buffer 104 105nREPL message logging is not enabled by default. Set `nrepl-log-messages` to `t` 106to activate it. Alternatively you can use kbd:[M-x] 107`nrepl-toggle-message-logging` to enable/disable logging temporary within your 108current Emacs session. Note that enabling message logging can impact 109performance. 110 111=== `cider-debug` complains that it "`failed to instrument ...`" 112 113In the REPL buffer, issue the following. 114 115 your.namespace> (ns cider.nrepl.middleware.util.instrument) 116 cider.nrepl.middleware.util.instrument> (def verbose-debug true) 117 118This will cause CIDER to print extensive information to the REPL buffer when you 119try 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] 120and copy this information. 121 122=== The REPL blows up when some function returns an URL 123 124Most likely you've encountered some issue with the `content-type` middleware. Generally, that's 125easy to confirm by inspecting the stracktrace: 126 127[source,clojure] 128---- 129user> (java.net.URI. "mailto:foo@bar.com") 130#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} 131java.net.UnknownServiceException: protocol doesn't support input 132 at java.base/java.net.URLConnection.getInputStream(URLConnection.java:840) 133 at cider.nrepl.middleware.slurp$slurp_url_to_content_PLUS_body.invokeStatic(slurp.clj:100) 134 at cider.nrepl.middleware.slurp$slurp_url_to_content_PLUS_body.invoke(slurp.clj:82) 135 at cider.nrepl.middleware.slurp$handle_slurp.invokeStatic(slurp.clj:117) 136 at cider.nrepl.middleware.slurp$handle_slurp.invoke(slurp.clj:109) 137---- 138 139You can disable the middleware like this: 140 141[source,lisp] 142---- 143(setq cider-repl-use-content-types t) 144---- 145 146It's disabled by default starting with CIDER 0.25. 147 148=== Debugging freezes & lock-ups 149 150Sometimes a CIDER command might hang for a while (e.g. due to a bug or a 151configuration issue). Such problems are super annoying, but are relatively easy 152to debug. Here are a few steps you can take in such situations: 153 154* Do kbd:[M-x] `toggle-debug-on-quit` 155* Reproduce the problem 156* Hit kbd:[C-g] around 10 seconds into the hang 157 158This will bring up a backtrace with the entire function stack, including 159function arguments. So you should be able to figure out what's going on (or at 160least what's being required). 161 162=== Warning saying you have to use newer nREPL 163 164CIDER currently requires at least nREPL 0.6 to work properly. As nREPL comes 165bundled with Leiningen and Boot, from time to time you might have to override the 166version supplied by them (e.g. if you're forced to use an older version of 167Leiningen or there's no release bundling the required nREPL version yet). Leiningen 168users can add this to their `profiles.clj` to force the proper dependency: 169 170[source,clojure] 171---- 172{:repl {:dependencies [[nrepl/nrepl "x.y.z"]]}} 173---- 174 175The procedure is pretty similar for Boot. 176 177IMPORTANT: Make sure you add the newer nREPL dependency to the `:dependencies` key instead 178of `:plugins` (where the `cider-nrepl` Lein plugin resides). That's a pretty common 179mistake. 180 181Generally you're advised to use the newest nREPL with CIDER, as bugs get fixed 182in pretty much every release. 183 184=== Missing clojure-... function after CIDER update 185 186Most likely you've updated CIDER, without updating `clojure-mode` as well. 187 188CIDER depends on `clojure-mode` and you should always update them together, as 189the latest CIDER version might depend on functionality present only in the latest 190`clojure-mode` version. 191 192=== I upgraded CIDER using `package.el` and it broke 193 194The built-in package manager isn't perfect and sometimes it messes up. If you 195just updated and encountered an error you should try the following before 196opening an issue: Go into the `.emacs.d/elpa` directory, delete any folders 197related to CIDER, restart Emacs and then re-install the missing packages. Note 198that the order here matters. 199 200=== I upgraded CIDER using `package.el` and nothing changed 201 202Emacs doesn't load the new files, it only installs them on disk. To see the 203effect of changes you have to restart Emacs. 204 205=== CIDER complains of the `cider-nrepl` version 206 207This is a warning displayed on the REPL buffer when it starts, and usually looks like this: 208 209____ 210*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! 211____ 212 213where `a.b.c` might be an actual version, like `0.17.0`, or it might be `not installed` or `nil`. 214The solution to this depends on what you see and on what you're doing. 215 216==== You see a number like `X.X.X`, and you're starting the REPL with `cider-connect` 217 218Your project specifies the wrong version for the cider-nrepl middleware. See the 219xref:basics/middleware_setup.adoc[instructions] 220in the "Middleware Setup" section. 221 222==== You see `not installed` or `nil`, and you're starting the REPL with `cider-connect` 223 224To use `cider-connect` you need to add the cider-nrepl middleware to your project. See the 225xref:basics/middleware_setup.adoc[instructions] 226in the "Middleware Setup" section. 227 228==== You see `not installed` or `nil`, and you're starting the REPL with `cider-jack-in` 229 230* Do `C-h v cider-inject-dependencies-at-jack-in`, and check that this variable is non-nil. 231* Make sure your project depends on at least Clojure `1.7.0`. 232* If you use Leiningen, make sure your `lein --version` is at least `2.9.0`. 233* If you use Boot and you've changed `cider-boot-parameters`, that's probably the cause. 234 235If the above doesn't work, you can try specifying the cider-nrepl middleware 236manually, as per the 237xref:basics/middleware_setup.adoc[instructions] 238in the "Middleware Setup" section. 239 240==== You see a number like `X.X.X`, and you're starting the REPL with `cider-jack-in` 241 242This means you're manually adding the cider-nrepl middleware in your project, 243but you shouldn't do that because `cider-jack-in` already does that for 244you. Look into the following files, and ensure you've removed all references to 245`cider-nrepl` and `nrepl`: `project.clj`, `build.boot`, 246`~/.lein/profiles.clj` and `~/.boot/profile.boot`. 247 248=== I get some error related to refactor-nrepl on startup 249 250The package `clj-refactor` would normally inject its own middleware on 251`cider-jack-in`, just as CIDER itself would. Usually that's not a 252problem, as long as you're using compatible versions of CIDER and 253`clj-refactor`, but if you're getting some error probably that's not 254the case. You've got two options to solve this: 255 256* Use compatible versions of the two projects (e.g. their most recent 257snapshots or most recent stable releases) 258* Disable the `clj-refactor` middleware injection: 259 260[source,lisp] 261---- 262(setq cljr-inject-dependencies-at-jack-in nil) 263---- 264 265=== Off-by-one column numbers 266 267Emacs and Clojure differ in their indexing of column numbers -- Emacs starts 268counting from 0 while Clojure starts from 1. Accordingly, the `cider-nrepl` 269middleware uses 1-based indexing and all conversions to 0-based indexing should 270be handled client-side. See https://github.com/clojure-emacs/cider/issues/2852. 271