Atom provides several tools to help you understand unexpected behavior and debug problems. This guide describes some of those tools and a few approaches to help you debug and provide more helpful information when submitting issues:
You might be running into an issue which was already fixed in a more recent version of Atom than the one you're using.
If you're using a released version, check which version of Atom you're using:
atom --version Atom : 1.8.0 Electron: 0.36.8 Chrome : 47.0.2526.110 Node : 5.1.1
Then check for the latest Stable version.
If there is a more recent release available, you can update to the most recent release with the auto-update functionality built in to Atom and the about package. You can open the About View by using the Atom > About menu option to see whether Atom is up-to-date, downloading a new update or click the button to "Restart and Install Update".
If there is a more recent release available, you can update to the most recent release with the auto-update functionality built in to Atom and the about package. You can open the About View by using the Help > About menu option to see whether Atom is up-to-date, downloading a new update or click the button to "Restart and Install Update".
If you're building Atom from source, pull down the latest version of master and re-build.
A large part of Atom's functionality comes from packages you can install. Atom will also execute the code in your init script on startup. In some cases, these packages and the code in the init script might be causing unexpected behavior, problems, or performance issues.
To determine if that is happening, start Atom from the terminal in safe mode:
This starts Atom, but does not load packages from
~/.atom/dev/packages and disables loading of your init script. If you can no longer reproduce the problem in safe mode, it's likely it was caused by one of the packages or the init script.
If removing or commenting out all content from the init script and starting Atom normally still produces the error, then try figuring out which package is causing trouble. Start Atom normally again and open the Settings View with Cmd+,Ctrl+,. Since the Settings View allows you to disable each installed package, you can disable packages one by one until you can no longer reproduce the issue. Restart Atom or reload Atom with Alt+Cmd+Ctrl+LCtrl+Shift+F5 after you disable each package to make sure it's completely gone.
When you find the problematic package, you can disable or uninstall the package. We strongly recommend creating an issue on the package's GitHub repository. The Atom FAQ has information on how to contact the maintainers of any Atom community package or theme.
Atom saves a number of things about your environment when you exit in order to restore Atom to the same configuration when you next launch the program. In some cases the state that gets saved can be something undesirable that prevents Atom from working properly. In these cases, you may want to clear the state that Atom has saved.
Danger: Clearing the saved state permanently destroys any state that Atom has saved across all projects. This includes unsaved changes to files you may have been editing in all projects. This is a destructive action.
Clearing the saved state can be done by opening a terminal and executing:
In some cases, you may want to reset Atom to "factory defaults", in other words clear all of your configuration and remove all packages. This can easily be done by opening a terminal and executing:
mv ~/.atom ~/.atom-backup
mv ~/.atom ~/.atom-backup
rename %USERPROFILE%\.atom .atom-backup
Once that is complete, you can launch Atom as normal. Everything will be just as if you first installed Atom.
Tip: The command given above doesn't delete the old configuration, just puts it somewhere that Atom can't find it. If there are pieces of the old configuration you want to retrieve, you can find them in the
If you develop or contribute to Atom packages, there may be left-over packages linked to your
~/.atom/dev/packages directories. You can use the
apm links command to list all linked packages:
apm links /Users/octocat/.atom/dev/packages (0) └── (no links) /Users/octocat/.atom/packages (1) └── color-picker -> /Users/octocat/github/color-picker
You can remove links using the
apm unlink command:
apm unlink color-picker Unlinking /Users/octocat/.atom/packages/color-picker ✓
apm links --help and
apm unlink --help for more information on these commands.
Tip: You can also use
apm unlink --all to easily unlink all packages and themes.
If you have packages installed that use native Node modules, when you upgrade to a new version of Atom, they might need to be rebuilt. Atom detects this and through the incompatible-packages package displays an indicator in the status bar when this happens.
If you see this indicator, click it and follow the instructions.
In some cases, unexpected behavior might be caused by settings in Atom or in one of the packages.
Check Atom's settings in the Settings View, there's a description of most configuration options in the Basic Customization section. For example, if you want Atom to hide the invisible symbols representing whitespace characters, disable the "Show Invisibles" option.
Since Atom ships with a set of packages and you can also install additional packages yourself, check the list of packages and their settings. For instance, if you'd like to get rid of the vertical line in the middle of the editor, disable the Wrap Guide package. And if you don't like it when Atom strips trailing whitespace or ensures that there's a single trailing newline in the file, you can configure that in the whitespace package's settings.
You might have defined some custom styles, keymaps or snippets in one of your configuration files. In some situations, these personal hacks might be causing the unexpected behavior you're observing so try clearing those files and restarting Atom.
If a command is not executing when you press a key combination or the wrong command is executing, there might be an issue with the keybinding for that combination. Atom ships with the Keybinding Resolver, a neat package which helps you understand what key Atom saw you press and the command that was triggered because of it.
Show the keybinding resolver with Cmd+.Ctrl+. or with "Keybinding Resolver: Show" from the Command palette. With the Keybinding Resolver shown, press a key combination:
The Keybinding Resolver shows you a list of keybindings that exist for the key combination, where each item in the list has the following:
The keybindings are listed in two colors. All the keybindings that are matched but not executed are shown in gray. The one that is executed, if any, is shown in green. If the command you wanted to trigger isn't listed, then a keybinding for that command hasn't been loaded.
If multiple keybindings are matched, Atom determines which keybinding will be executed based on the specificity of the selectors and the order in which they were loaded. If the command you wanted to trigger is listed in the Keybinding Resolver, but wasn't the one that was executed, this is normally explained by one of two causes:
The key combination was not used in the context defined by the keybinding's selector
For example, you can't trigger the keybinding for the
tree-view:add-file command if the Tree View is not focused.
There is another keybinding that took precedence
This often happens when you install a package which defines keybindings that conflict with existing keybindings. If the package's keybindings have selectors with higher specificity or were loaded later, they'll have priority over existing ones.
Atom loads core Atom keybindings and package keybindings first, and user-defined keybindings last. Since user-defined keybindings are loaded last, you can use your
keymap.cson file to tweak the keybindings and sort out problems like these. See the Keymaps in Depth section for more information.
If you notice that a package's keybindings are taking precedence over core Atom keybindings, it might be a good idea to report the issue on that package's GitHub repository. The Atom FAQ has information on how to contact the maintainers of any Atom community package or theme.
You can determine which fonts are being used to render a specific piece of text by using the Developer Tools. To open the Developer Tools press Alt+Cmd+ICtrl+Shift+I. Once the Developer Tools are open, click the "Elements" tab. Use the standard tools for finding the element containing the text you want to check. Once you have selected the element, you can click the "Computed" tab in the styles pane and scroll to the bottom. The list of fonts being used will be shown there:
When an unexpected error occurs in Atom, you will normally see a red notification which provides details about the error and allows you to create an issue on the right repository:
If you can reproduce the error, use this approach to get the full stack trace and report the issue.
Not all errors are logged with a notification so if you suspect you're experiencing an error but there's no notification, you can also look for errors in the developer tools Console tab. To access the Console tab, press Alt-Cmd-ICtrl-Shift-I to open developer tools and then click the Console tab:
If there are multiple errors, you can scroll down to the bottom of the panel to see the most recent error. Or while reproducing an error, you can right click in the Console tab panel, select
Clear console to remove all Console output, and then reproduce the error to see what errors are logged to the Console tab.
Note: When running in Dev Mode, the developer tools are automatically shown with the error logged in the Console tab.
When Atom crashes, you will find a crash dump in Console.app. You can launch Console.app using Spotlight or you can find it in
/Applications/Utilities/Console.app. Once you have launched the program, you can find the latest crash dump by following these instructions:
Atomand ends with
Once you have the crash dump, you can save it to send in later if it is needed for debugging.
When Atom crashes, you will find a crash dump inside your
%TEMP%\Atom Crashes directory. It will be the newest file with the
.dmp extension. Once you have the crash dump, you can save it to send in later if it is needed for debugging.
When Atom crashes, it should write a core dump if system settings permit. In order to find whether the core dump is written and to where, consult the documentation for your distribution of Linux. Once you have the core dump, you can save it to send in later if it is needed for debugging.
If Atom is taking a long time to start, you can use the Timecop package to get insight into where Atom spends time while loading.
Timecop displays the following information:
If a specific package has high load or activation times, you might consider reporting an Issue to the maintainers. You can also disable the package to potentially improve future startup times.
If you're experiencing performance problems in a particular situation, your Issue reports will be more valuable if you include a saved profile from Chrome's CPU profiler that gives some insight into what is slow.
To run a profile, open the Developer Tools with Alt+Cmd+ICtrl+Shift+I. From there:
Once that is done, then perform the slow action to capture a recording. When finished, click "Stop". Switch to the "Chart" view, and a graph of the recorded actions will appear. You can save and post the profile data by clicking "Save" next to the profile's name in the left panel.
To learn more, check out the Chrome documentation on CPU profiling.
If the time for loading the window looks high, you can create a CPU profile for that period using the
--profile-startup command line flag when starting Atom:
atom --profile-startup .
This will automatically capture a CPU profile as Atom is loading and open the Developer Tools once Atom loads. From there:
You can then include the startup profile in any Issue you report.
If you are having issues installing a package using
apm install, this could be because the package has dependencies on libraries that contain native code. This means you will need to have a C++ compiler and Python installed to be able to install it. You can run
apm install --check to see if the Atom package manager can build native code on your machine.
Check out the pre-requisites in the build instructions for your platform for more details.