1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
|
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</kbd> `toggle-debug-on-error`.
Another good idea is to check the exchange of requests and responses between
CIDER and the nREPL server. You can find them in the `*nrepl-messages*` buffer,
provided you've enabled nREPL message logging.
## Debugging CIDER commands
Emacs features a super powerful built-in
[Emacs Lisp debugger](http://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html)
and using it is the best way to diagnose problems of any kind.
!!! Tip
Here's a [great crash course](https://www.youtube.com/watch?v=odkYXXYOxpo) 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</kbd>
to see which command is associated with some keybinding)
* Find the source of the command (e.g. by using <kbd>M-x</kbd> `find-function`
<kbd>RET</kbd> `function-name`)
* Press <kbd>C-u C-M-x</kbd> 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 [built-in
profiler](https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html). Using
it is pretty simple:
1. Start it with <kbd>M-x</kbd> `profiler-start`.
2. Invoke some commands.
3. Get the report with <kbd>M-x</kbd> `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</kbd>.
## 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</kbd>, 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</kbd> `nrepl-toggle-message-logging`
to enable/disable logging temporary within your current Emacs session.
### `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</kbd>). [File an issue](https://github.com/clojure-emacs/cider-nrepl/issues/new)
and copy this information.
### 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</kbd> `toggle-debug-on-quit`
* Reproduce the problem
* Hit <kbd>C-g</kbd> 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 nREPL 0.2.12+
CIDER currently requires at least nREPL 0.2.12 to work properly (there were some
nasty bugs in older version and no support for tracking where some var was
defined in the source code). Leiningen users can add this to their
`profiles.clj` to force the proper dependency:
```clojure
{:repl {:dependencies [[org.clojure/tools.nrepl "0.2.12"]]}}
```
Make sure you add the newer nREPL dependency to the `:dependencies` key instead
of `:plugins` (where `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.
Note, that running `cider-jack-in` from outside the scope of a project will
result in the **older (0.2.6) nREPL dependency being used** (at least on Leiningen
2.5.1). This is likely a Leiningen bug.
### 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. Things will break!
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
[instructions](https://docs.cider.mx/en/latest/installation/#ciders-nrepl-middleware)
on the Installation 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
[instructions](https://docs.cider.mx/en/latest/installation/#ciders-nrepl-middleware)
on the Installation 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.6.1`.
- If you use boot and you've changed `cider-boot-parameters`, that's probably the cause.
If the above doesn't work, you can try specifying the cider-nrepl middleware
manually, as per the
[instructions](https://docs.cider.mx/en/latest/installation/#ciders-nrepl-middleware)
on the Installation 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 `tools.nrepl`: `project.clj`, `build.boot`,
`~/.lein/profiles.clj` and `~/.boot/profile.boot`.
### 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:
```el
(setq cljr-inject-dependencies-at-jack-in nil)
```
|
