-
Notifications
You must be signed in to change notification settings - Fork 0
Platform Notes & Troubleshooting
Because Keystone interfaces directly with low-level kernel routines via the Chromium Debugger Protocol and requires native file system hooks to construct localized targets, compilation environments may face specific hardware blocks.
The macOS builder (@electron-forge/maker-dmg) depends on a library called macos-alias, which contains native C++ binaries. If lifecycle scripts are globally blocked on your profile during workspace installation routines, the native compilation step will skip over this dependency, causing the builder to throw a missing volume.node module crash.
If running a compilation loop throws a missing module exception inside your node_modules/macos-alias/ workspace structure, bypass the global manager entirely and compile the code block manually:
# 1. Access the target directory location
cd node_modules/macos-alias
# 2. Force a raw script compilation pass
npm run install --ignore-scripts=false
# 3. Step back to your primary project root
cd ../..
# 4. Trigger an immediate native layout rebuild loop
npx electron-rebuild-
Administrative Privileges: If npm install flags file system blockages or fails partway through with permission access blocks, terminate the session and re-open your terminal environment using Run as Administrator.
-
Antivirus False Positives: When executing the chrome-headless-shell binary downloader tool, Windows Defender or deep heuristic endpoint monitors may flag the background browser automation binary as malicious. This is a common warning triggered by script-driven browser assets. You can safely allow it through.
Minimal server packages or clean installations of distributions like Debian and Ubuntu often omit graphics engine libraries needed to run automated background instances of chrome-headless-shell.
If generating diagnostic reports throws a missing shared library exception, install the following package dependencies directly through your target system distribution tool:
sudo apt install libnss3 libatk-1.0-0 libcups2 libgbm1 libasound2