Document common build issues and errors (and their solutions)

[DeeDeeG]

Error: Cannot back up /home/[user]/atom/node_modules/github/node_modules; /home/[user]/atom/node_modules/github/node_modules.bak already exists

This happens when script/build exits early. There are two possible solutions:

1. Inspect node_modules/github/node_modules.bak and node_modules/github/node_modules, see which one appears to have the original content, and ensure it ends up in node_modules/github/node_modules. Once the correct content is placed there, delete node_moduled/github/node_modules.bak. You can now try again to run script/build.
2. Run script/clean and script/bootstrap for a completely clean bootstrapping process. You can then run script/build --no-bootstrap.

Error: ENOSPC: no space left on device, write

This means your hard drive is full, and some space needs to be cleared. Try to delete some large files from your hard drive that you no-longer need. Installing Atom takes several gigabytes of free space. 10GB free should be enough, but more free space is even better up to about 20 GB, which should be more than enough.

Skipping installation. Specify the --install option to install Atom; Segmentation fault (core dumped)

This has been happening often on Linux, lately. There's no obvious reason why it's happening, unfortunately. On the other hand, this error usually happens after the build has fully finished, and created your .deb and/or .rpm package if you specified the flags to build those, so the solution for now is to just ignore the message. If this happens to a CI run for one of your Pull Requests, we will gladly re-run the failed CI job(s) for you until it passes.

Update: This should be fixed by atom#21284 as of early September 2020.

[Error [ERR_PACKAGE_PATH_NOT_EXPORTED] [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main resolved in /home/[user]/atom/out/app/node_modules/github/node_modules/@babel/helper-compilation-targets/package.json

This happens when you build Atom with more recent versions of Node. Node 12.17.0, Node 13.2.0, and Node 14.0.0 and newer have a change that is incompatible with older babel, which Atom still uses. (atom#21091) Atom needs to update its babel dependency. See #67.

For now, the solution is to use Node 10 (10.12.0 or newer), or Node 12 (12.16 or older).

Update: This should be fixed by atom#21657 as of November 2020

The bootstrap or build process is stalled or frozen, with no progress for a long time

This happens occasionally, most often on Windows, for unknown reasons. Try pressing the "Enter"/"Return" key on your keyboard, and the bootstrap/build process might continue, appearing to "jump back to life."

gyp ERR! stack Error: Could not find any Visual Studio installation to use

This happens when the native C++ build system node-gyp can't find a usable version of Visual Studio on your Windows system. This can be for a number of underlying reasons. Here are solutions, in order of how easy they are:

• Check your npm configuration. Run npm config get and look for msvs_version. If it is set, you should run npm config delete msvs_version or npm config --global delete msvs_version (or both, just to be certain you deleted the configuration).
• Make sure you have an actually supported version of Visual Studio (or Visual Studio C++ Build Tools) installed! Recommended versions are version 2015 and version 2017. Version 2019 might work, but is not guaranteed to be supported, so your mileage may vary.
  • Relatedly: Do you have all of the necessary components? You should check the "C++ build tools" workload when installing. The exact minimum necessary sub-components are: MSVS v14x, Windows 10 SDK/Windows 8 SDK.
• Are you running an old version of npm? Run npm --version to find out. Npm should be 6.10.1 or greater (older versions of npm were not as good at finding Visual Studio installed to your system!) If you must use an older npm (are you sure you have to run an older npm?) and you must use Visual Studio 2015 (are you sure?) then this is the one circumstance in which the npm config msvs_version must be set. Run the following: npm config --global msvs_version=2015.

No receipt for 'com.apple.pkg.CLTools_Executables' found at '/'.

No receipt for 'com.apple.pkg.DeveloperToolsCLILeo' found at '/'.

No receipt for 'com.apple.pkg.DeveloperToolsCLI' found at '/'.

gyp: No Xcode or CLT version detected!

This usually happens after a system update on macOS Catalina. The solutions are listed here: https://github.com/nodejs/node-gyp/blob/master/macOS_Catalina.md

What usually works for me is:

• sudo rm -rf /Library/Developer/CommandLineTools
• xcode-select --install
  • Click through the GUI prompt to install Command Line Tools for XCode. Wait for the full installation to finish. Particularly, ignore any notifications of updates from Software Update in System Preferences until the install is finished.

[aminya]

Please open the issue in the documentation repository. We can't document anything here.

[DeeDeeG]

This issue is the documentation. It's not supposed to be all official yet, just that I need a place to put these. Consider this issue a publicly readable pastebin or text document while I find the various error messages. Adding them to the documentation repo is too slow and too much friction, unless I think I've found them all already.

[aminya]

Refer to #118 (comment)

[SolarAquarion]

internal/modules/cjs/loader.js:430
      throw e;
      ^

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: Package subpath './bin/npm-cli' is not defined by "exports" in /usr/lib/node_modules/npm/package.json

Is this one of the common build failures?

[DeeDeeG]

@SolarAquarion hmm, I've never seen that one before.

If you want to open a discussion or talk about it on the Discord chat server, I may be able to help diagnose the issue as/when I get the time.

There is also the official Atom discussion forum, if you'd rather post somewhere more official to the main Atom project: https://discuss.atom.io/