[WARNING] No nREPL middleware descriptor in metadata of #'some.middleware/wrap-foo, see nrepl.middleware/set-descriptor!This section of the manual tries to summarize the most common problems that you may encounter while using nREPL and their solutions.
Generally it’s also a good idea to check whether the problem you’ve experienced is not a bug that’s already reported on our issue tracker.
If your client cannot connect to a running nREPL server:
Verify the server is actually running and listening on the expected port.
Check that the .nrepl-port file (if present) contains the correct port.
A stale .nrepl-port file left over from a previous session will point clients at
a port where nothing is listening. Delete it and restart the server.
If the server is bound to 127.0.0.1 (the default), connections from other
machines will be refused. Use :bind "0.0.0.0" to listen on all interfaces,
but be aware of the security implications — see TLS if
you need remote access.
On some systems, firewalls or security software may block connections to ephemeral ports.
If you see an "Address already in use" error when starting a server, another
process is already listening on that port. Either stop the other process, or
start nREPL on a different port (:port 0 will pick a random available port).
If an evaluation never returns:
The code may be performing blocking I/O or running an infinite loop.
Try sending an interrupt op to stop it.
If printing a large or infinite lazy sequence, *print-length* may not be
set. Bind it to a reasonable value (e.g. 100) in your session to avoid
this.
Middleware that wraps printing (e.g. nrepl.middleware.print) respects
*print-length* and *print-level* — make sure these are set in the
session where the evaluation is running.
On Java 21+, Thread.stop() has been disabled by the JDK. nREPL ships a
native JVMTI agent to restore thread-stopping capability, but it requires the
JVM flag -Djdk.attach.allowAttachSelf to be set at startup.
If interrupt doesn’t stop a running evaluation on Java 21+, make sure this flag is present. See Enable libnrepl JVMTI agent for details.
On earlier Java versions, interrupt should work out of the box via
Thread.stop().
If you see warnings like:
[WARNING] No nREPL middleware descriptor in metadata of #'some.middleware/wrap-foo, see nrepl.middleware/set-descriptor!This means you’re loading middleware that is incompatible with the current
version of nREPL. Make sure you’re using the latest versions of all middleware
libraries and that your project does not pull in a stale tools.nrepl
dependency (the predecessor to nREPL).
If a middleware you’ve configured doesn’t seem to have any effect:
Use the describe op to inspect the server’s active middleware and ops.
If your middleware’s op doesn’t appear, it was not loaded.
Check that the middleware var is fully qualified and resolves correctly.
Middleware ordering matters — set-descriptor! declares :requires and
:expects dependencies. If these aren’t satisfied, the middleware may be
silently excluded from the handler stack. Check the server output for
warnings.
If you’re having trouble with TLS connections, the most common issues are:
Certificate not found — verify the path in :tls-keys-file points to an
existing file.
Handshake timeout — the default handshake timeout is 30 seconds. If clients are on a slow network, this may not be enough.
"Cannot use same keys as server" — the server rejects connections where the client presents the same certificate as the server. Generate separate client and server key files.
See TLS support for setup instructions.
If you experience problems running lein repl:
Make sure your project uses Clojure 1.9+ and Java 8+.
Make sure you’re using the latest versions of nREPL middleware.
If Leiningen bundles an older nREPL version, you can override it by adding
nrepl as an explicit dependency in your project.clj.
Can you improve this documentation? These fine people already did:
Oleksandr Yakushev, Bozhidar Batsov, Michael Griffiths & Dominic MonroeEdit on GitHub
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |