Clojure Error Message Catalog

a catalog of common Clojure errors and their meanings

What is it?

We are experimenting with starting a community driven catalog of common errors. The main categories will be Clojure, ClojureScript and libraries.

The idea is that people can submit an issue with a particular error, or make a pull request with the error, description and hopefuly one or two solutions to resolve it.

Eventually, the plan would be to create a site where you could paste errors and search for them that way, but it would make sense to start with a GitHub repo to see if there's interest. Hopefully, this will also help identify the most common errors people have trouble with and make error reporting better in Clojure itself.

This project was inspired by the way Elm does this, where they have a repo for this purpose, and then provide custom compiler errors for these cases.

We need your errors!

This catalog is community driven, hence your contribution to this is invaluable.

It is very simple to contribute / share errors, exceptions, causes and possible solutions. There are 3 main sections of the catalog:

1. Clojure errors

• Live under clj
• Here we collect all Clojure core errors: i.e. errors that are raised from/by Clojure itself.

2. ClojureScript errors

• Live under cljs
• Here we collect all ClojureScript core errors: i.e. errors that are raised from/by ClojureScript itself.

3. Library errors

• Live under lib
• Here we collect all errors that are raised from/by any Clojure / ClojureScript library (Ring, Compojure, your library, etc..)

How to submit a new error

In order to contribute, please check that the error is not already in the catalog. If it is and you need to add / change anything, just send a pull request.

Error file name

Errors are submitted as markdown files (i.e. .md). The file name would be very close to the exception.

For example, let's take an exception:

#object[mount.core.DerefableState 0x52691944 {:status :failed, :val #error {
:cause "mount.core.DerefableState cannot be cast to clojure.lang.IFn"

So something like derefablestate-cannot-be-cast-to-ifn.md would be a great, descriptive file name for this error.

Error file format

Would be really helpful to have the following in the error file:

• Exception
• Description of the exception
• Common cause(s)
• Solutions

Share a file that describes these sections in a markdown format:

## Title: Exception message
### Description: general description of the exception
### Cause 1: Cause title
### Solution 1
...
### Cause n: cause n title
### Solution n

Why the "format"?

Following this format / guideline allows this error catalog to be processed into a format that can be also readable by programs (i.e. not just us, humans). Which enables great things like [contextual search] (https://en.wikipedia.org/wiki/Contextual_searching), IDE/tooling integration for suggestions, etc.

Check out this error file to visualize the required format.

Where to place the file?

Since there are 3 main sections (clj / cljs / lib) place it under the section that matches the nature of the error.

For example the error ("mount.core.DerefableState cannot be cast to clojure.lang.IFn") would live under lib/mount/ since it is caused by the library that is called mount.

In case the error is Clojure core related, place is under clj.

ClojureScript core related errors would go under cljs.

-

So the steps to contribute are:

• fork this repo
• Once the error file is ready to be contributed, just send a pull request to the repo.

In case you have any questions, suggestions, please let us know via opening an issue or pinging us on clojurian slack (@yogthos, @tolitius).

Website

The very beginnings of a website where people can browse and search the error repo, and submit new errors, is here. Contributions to the website are also extremely welcome. It's currently planned to be a very simple static website.

License

Copyright © 2016 Clojure Community

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.