SPC q r (
restart-emacs) is a quick way to resolve some issues, especially when installing multiple packages. Some Emacs packages depend on others being present, which may not be the case when first installing.
SPC f e D (
ediff) to compare your
.spacemacs configuration with the default Spacemacs configuration.
k to navigate the differences,
b to copy a change from the Spacemacs configuration to your own.
q to quit comparing,
? for more help.
Switch to the Spacemacs develop branch to get the latest fixes and features (until version 0.300 is release to master).
View the Spacemacs issues on GitHub before submitting a new issue. You may find a fix to your problem, even if only a temporary solution.
SPC h d s will generate system information in the kill ring, so you can confirm an existing issue with meaningful data, helping to identify the root cause.
Also review the GitHub issues for a specific package that may be causing issues. A search for
emacs package-name should help you find its GitHub repository.
Ask the community
If you are unsure if you have found an issue, or do not understand why some behavior is happening, then ask the Spacemacs community, they are very helpful and friendly.
- Spacemacs Gitter chat - any aspects of Spacemacs
- #Spacemacs on Clojurians Slack community - Clojure specific discussions (create a free account)
SPC h I will create an issue on the Spacemacs GitHub repository that included the basic Spacemacs environment details, helping others understand and resolve the issue effectively.
Read how to make a great bug report
Please do not raise an issue directly via the GitHub website. If you do, you will slow down the response to this issue and the first response to your issue will be to provide system information.
Specific Package Issue
Delete a package from the
~/.emacs.d/elpa directory if it does not seem to be working, is generating warnings or errors or is simply not working correctly.
SPC q r to restart Spacemacs and download the package again.
Issues after package update
If multiple packages are causing issues after an update, or you are short on time to diagnose an issue, then rollback to the packages used before the update.
SPC b h to visit the Spacemacs home page and select Rollback Package Update
Pinning packages / using a recipe
If a package has an issue in its newest version, you can configure spacemacs to use an older version of the package.
Scorched Earth approach
~/.emacs.d/elpa director and
SPC q r to restart Spacemacs. This will remove any complied Emacs packages that may have become corrupted or replace older packages that are now causing issues.
As there are 100's of packages, the scorched earth approach of just deleting them and downloading fresh copies can be surprisingly effective at resolving issues with very little effort.
The Spacemacs debugging page explains concepts needed to debug Spacemacs and to report issues in an useful way.
Issues with spawnd processes
SPC a p (
list-processes) lists the processes started by or from within Spacemacs, eg. for Clojure its
nrepl-connection processes when running
SPC a P (
proced) to see all operating system processes.
d to immediately kill a process (no prompt is given to confirm kill action).
The process list shows the command used to start the process, which can be useful in diagnosing issues.
RET on buffer name in the process list will open that buffer in a separate window.
If there are problems shutting down the REPL,
, s q q (
cider-quit), check to see if the CIDER nrepl-server or nrepl-connection process has been killed.
q to quit the process list buffer.
SPC a P lists all operating system processes
SPC SPC helm-top runs a process list
SPC SPC profiler-start will start monitoring how much CPU and memory resources that different parts of Emacs are using. The profiler is especially useful if there are slow running commands or Emacs is unresponsive at times.
SPC SPC profiler-report displays buffers showing the results of profiling Emacs.
SPC SPC profiler-stop to stop profiling Emacs.