The error page submitted on 04/29 uses a somewhat different format than is recommended on the readme. It was done using this format based on conversation in slack about whether error pages should ultimately reflect a single exception, or a single cause of a single exception. The decision made on the fly was that one page equals one error. To fit that, the referenced page uses the following Markdown format for sections:

## <Text of the exception message>
### General description of exception
### Cause 1
### Solution 1
### Cause 2
### Solution 2

I propose that the readme be changed to reflect that (and I'd be happy to take that on), but wanted to get buy-in from other folks on the project first. This may not be the final decision on format, but I think it makes sense to have the readme reflect our most current understanding.

Note that this change is consistent with issue 14, but potentially conflicts with some of the formats proposed in issue 6.

I had an issue with a dependency conflict yesterday between aws and transit.

I don't want to call out those libs in particular as it's a general problem that happens all the time when you mix libs and they have different transitive dependency versions.

In this case I got a ClassNotFound error which is misleading. After a lot of head scratching I eventually tracked it down to a transitive version conflict for jackson.core. Let's just say that was not obvious - even if, like me, you do have a Java / Maven background.

The immediate fix was to add an exclusion on one of the libraries but that might break as each library version evolves.

How can I add this error / type of error to your catalog?

There exists a catalog of 50 error patterns documented with regex here:

• assertion-error-with-argument
• assertion-error-without-argument
• class-cast-exception-cannot-cast-to-map-entry
• class-cast-exception
• assoc-parity-error
• wrong-number-of-args-passed-to-a-keyword
• illegal-argument-no-val-supplied-for-key
• illegal-argument-vector-arg-to-map-conj
• illegal-argument-cannot-convert-type
• illegal-argument-even-number-of-forms
• illegal-argument-even-number-of-forms-in-binding-vector
• illegal-argument-needs-vector-when-binding
• illegal-argument-type-not-supported
• illegal-argument-parameters-must-be-in-vector
• illegal-argument-exactly-2-forms
• duplicate-key-hashmap
• cant-call-nil
• compiler-exception-wrong-number-of-arguments-to-recur
• compiler-exception-on-improper-use-of-arg-literal
• index-out-of-bounds-index-provided
• string-index-out-of-bounds
• index-out-of-bounds-index-not-provided
• arity-exception-wrong-number-of-arguments
• null-pointer-non-existing-object-provided
• null-pointer-non-existing-object-not-provided
• unsupported-operation-wrong-type-of-argument
• compiler-exception-must-recur-from-tail-position
• class-not-found-exception
• number-format-exception
• lisp-reader-exception-long-error-error
• reader-tag-must-be-symbol
• invalid-tolken-error
• invalid-tolken-error
• syntax-error-cant-specifiy-over-20-args
• compiler-exception-first-argument-must-be-symbol
• compiler-exception-cannot-take-value-of-macro
• compiler-exception-cannot-resolve-symbol
• compiler-exception-map-literal-even
• compiler-exception-unmatched-delimiter
• compiler-exception-too-many-arguments
• compiler-exception-too-few-arguments
• compiler-exception-end-of-file
• compiler-exception-end-of-file-string
• compiler-exception-no-such-var-with-namespace
• compiler-exception-no-such-var-no-namespace
• compiler-exception-no-such-namespace
• java.lang.Exception-improper-identifier
• compiler-exception-even-numbers-in-binding-vector
• compiler-exception-even-number-of-forms-needed
• compiler-exception-wrong-number-of-arguments

As seen here.

(Maybe make a separate CONTRIBUTING.md file as well?)

I think these error docs might be moving in the wrong direction:

• clojure-lang-persistentlist-cannot-be-cast-to-clojure-lang-symbol
• dont-know-how-to-create-iseq-from
• java-lang-string-cannot-be-cast-to-clojure-lang-ifn
• nth-not-supported-on-this-type

Some errors can happen in a multitude of contexts, but the above errors attribute them to specific cases only, though they obviously can show up elsewhere. Sorry, this was just my gut reaction, and I haven't thought about it too much yet, but I thought others might be thinking the same thing, so I wanted to bring it up early.

My secondary reaction is that following in this direction could amount to us documenting error reports for every function/macro arg type. Surely there is a better plan for dealing with this class of errors?

(sorry for posting this as issue instead of a pull request)

While I was half asleep I was using a threading macro (->) to filter some elements:

(-> [1, 2, 3, 4, 5]
  (filter odd?))

and got confused by the exception this caused. Later I realized I should have used ->> instead.

FYI, this repo is on the home page of Hacker News now https://news.ycombinator.com/item?id=13761898

At the risk of slowing down contributions, would it be worth documenting these errors in edn/cljc, and then generating documentation from them? This would allow better tooling to be built around the errors.

I guess the risk is that errors aren't improved in clojure.core upstream since it might be seen as solved by tooling, which I think is the wrong approach overall.

http://dev.clojure.org/display/design/Macro+Grammars#MacroGrammars-Examplebugsthatcouldberesolvedbymacrogrammars

Git isn't a big obstacle for many programmers, but we could decrease submission friction significantly further, in my opinion, by creating a website with a submission form. This would have the additional benefit of ensuring a consistent format (by separating the form into fields for error, description, cause(s), solution(s), possibly others).

Further, a basic website would be a place to display error pages in an attractive format for users who were only interested in looking for help on the error they've encountered, and provide a convenient search mechanism.

The main inspiration here is the Scala Clippy website, which has tabs for usage instructions, contribution form, and a browse page, as well as links to the project's github page and to the project's gitter chat.. Seems like a simple and effective model. There'd presumably be a cron job or equivalent to periodically update the site from the repo. My first thought for handling submissions is to write code to convert them to PRs. Alternately, the final source of truth could switch to being a persistent database, but having it be the repo seems good enough for now to me.

I'm happy to work on it, but given my current time constraints it would be a while before I had anything ready to go. If someone else wants to take it on, that's great. We'd also need to have a hosting solution of some sort.

This may not be high enough priority to tackle immediately, but I wanted to get it out there for discussion & input, and I certainly see some advantage to prioritizing creating a minimum-friction way for people to submit errors and/or solutions.

Feedback & input appreciated.

Found this with a teaching session with a Clojure beginner:

IllegalArgumentException Wrong number of args passed to keyword: :bread

Clearly this only works when the first item in the list is a keyword (in this case :bread).

I'm a complete beginner with Clojure (mainly focused on Clojurescript) so maybe I'm thinking completely wrong. I do appreciate this initiative since error message in Clojure (coming from a non-java background) is very foreign and hard to parse.

But, would it be possible to hook into something in lein/boot when an error happen and automatically link to something in this catalog? That would make usage of this so much easier.