Troubleshooting

Have you read all the documentation at ensime.org/editors/emacs? Please do, we put a lot of effort into it.

Most problems can be resolved easily by following a simple process. Please do not skip these steps.

There are three classes of problem:

Problem starting the ENSIME server

  1. update ensime for Emacs, M-x list-packages RET U RET x.
  2. update your build tool plugin and re-run the .ensime generator.

Check the *ENSIME-...* server buffer for exceptions. If there is anything suspicious, kill the buffer (this stops the server), delete the .ensime_cache, and restart.

If that doesn’t work, escalate matters: nuke old versions of ENSIME and restart Emacs:

rm -rf ~/.ivy2/cache/org.ensime \
       ~/.ivy2/local \
       ~/.coursier/cache/v1/https/oss.sonatype.org/content/repositories/snapshots \
       ~/.emacs.d/ensime \
       ~/.emacs.d/elpa/ensime* \
       ~/.emacs.d/elpa/scala-mode* \
       ~/.emacs.d/elpa/sbt-mode*

If that doesn’t work, move your ivy folder aside, it has probably become corrupted:

mv ~/.ivy2 ~/.ivy2.bak

Problem with red squiggly lines or broken completion / types

As a side effect, you’re probably experiencing hanging, remember to C-g or ESC ESC ESC to get Emacs back instantly.

  1. compile your project, or open all dependent scala files
  2. restart the presentation compiler: C-c C-c r (ensime-reload-open-files)

If that doesn’t work, try a few more things:

  1. restart the server with M-x ensime-reload
  2. if macro related, close the file defining the macro (known and sponsored issue)
  3. if compiler plugin related, ensure plugins are in your .ensime (via your build tool)

As documented in more detail in our Contributing Guide, ENSIME relies on type information provided by Scala’s Presentation Compiler and it is known to issue false positives. But it is easier than you might think to fix the problems upstream.

To help you diagnose problems, we wrote PC Plod. The first thing you can do is to write a PC Plod unit test for the library that you are using to raise awareness with the author of that library that they not compatible with the presentation compiler (and error reporter).

Anything else

  1. fully compile your project (did you skip the User Guide)? Time to read it, honestly it’s full of good stuff.
  2. following the steps in “Problem starting the ENSIME server” to ensure all your software is recent (this solves more than you’d expect)
  3. check all ENSIME FAQ issues and do a quick search.

If that solved your problem, great!

If not, please join the conversation at gitter.im/ensime/ensime-emacs and let it be known that you have followed this guide. If you do not provide a reproduction in the form of a project, it is extremely unlikely that anybody will be able to help you.

Do not post stacktraces on the gitter channel, instead yank the contents of M-x ensime-troubleshooting into a gist.

If you think you’ve found a bug you can file it at github.com/ensime/ensime-emacs but do not ignore the bug report template or your ticket will be closed immediately.

Remember, everybody is here to help, but nobody is paid to maintain ENSIME (not even the sponsored developers). For ENSIME to be sustainable, we need you to engage in the bug fixing process rather heavily and (ideally) submit a pull request with a fix.



[edit]