How to understand Clojure stacktraces

Written by Eric Normand. Published: February 28, 2017. Updated: April 25, 2018.

Clojure error messages and stacktraces are the number one most complained-about feature of Clojure. I agree they're bad. There are many levels of abstraction that the problem can exist in. For instance, it could be a reader error (syntax error), a type error (expecting a different type), an argument order/number error, etc. I wish I had a nice analysis showing you how to identify each type of error. But I don't!

What I do have is a bunch of resources. As a major problem in the Clojure language, rest assured that a lot of energy is spent on it. There are blog posts, stack overflow questions, utilities, and major work in the language. Here are some resources:

How To Understand Clojure Stacktraces And Error Messages

Christopher Bui has written a nice guide for beginners.

Clojure Stack Traces for the Uninitiated

Connor Mendenhall gives some beginner tips for reading stacktraces.

Prone

Prone is a cool middleware for Ring applications that catch exceptions and give them to you with a nice UI in the browser. It's one of the first things I add when starting a new web project.

clj-stacktrace

This older library prints stacktraces in a better way. Clojure functions are converted to their namespace/name format instead of their canonical JVM name with dollar signs, and things are aligned to be more easily read.

Clojure Error Message Catalog

This is a project to document error messages in Clojure with their interpretations and solutions. It is similar to the Elm version.

clojure.spec

clojure.spec, due out in Clojure 1.9, promises to make a lot of error messages much better. A lot of the difficulty with error messages in Clojure is that there are macros (yet another layer of abstraction). clojure.spec gives you a way to parse macros (and other syntax) with much better error messages.

For a preview of how spec will help, check out Illuminated Macros and Improving Clojure's Error Messages with Grammars, which came out before spec but use similar solutions.

Conclusion

With spec, I am very optimistic about Clojure error messages. In the next five years, I can see them getting really good. In the meantime, Clojure error messages are just something you'll have to learn how to read.

I wish I could wave a wand and give you all of the experience needed to read error messages. Error messages are a problem in many languages and Clojure's follow that tradition :)

If you're interested in learning Clojure, don't be discouraged by the error message. Nor should the JVM scare you off. That's why I created the JVM Fundamentals for Clojure course. It's over five hours of video teaching lots of things from my experience with the JVM that I still use with Clojure.