FAQ | ElectronEgg

Frequently Asked Questions

This section summarizes common issues encountered during development, helping developers quickly find solutions.

If you cannot find your issue here, you can also check the issue tracker:

1: Download resources timeout during packaging

bash

# Use the domestic mirror, see the Installation or Build Software tutorial

2: Packaging failure (exception)

bash

Error 1: python ...
Solution: Upgrade the build package, npm install electron-builder@23.0.6

bash

Error 2: Packaging error Fatal error: Unable to commit changes
Reason:
1. Is the disk full? This issue stumped me for half an hour, though not long, it was a basic mistake.
2. Antivirus software. I closed the computer manager and it worked. There's also McAfee and other antivirus programs.
3. When using the makensis package, if the account name is in Chinese, the build may fail.
Solution:
1. Clean up disk space
2. Exit antivirus software
3. https://www.azimiao.com/6250.html

bash

Error 3: ...resource\app.asar does not exist ...
Solution: In the electron-egg/ directory, if there is an app directory, it must be a plain file directory, not a project directory.
For example, the app/ directory cannot contain .git, package.json, node_modules, etc.

bash

Error 4: ...Need executable 'ar' to convert dir to deb
Reason: The fpm tool requires the ar command to package deb. Install binutils.
Solution: sudo apt install binutils

bash

Error 5: ...Cannot find module 'fs/promises'
Reason: The electron-builder package version is too high, some syntax is incompatible.
Solution: Downgrade electron-builder version, reinstall package: electron-builder <= 22.10.5

bash

Error 6: ...ERR! better-sqlite@7.6.2 install ...
Reason: sqlite requires a higher version of node.js
Solution: Update node.js >= 14.21.1

bash

Error 7: ... errorOUt=/home/hzx/.cache/electron-builder/fpm/fpm-1.9.3-2.3.1-linux-x86/lib/ruby/bin/ruby ...
Reason: fpm does not have a matching ARM package, so it downloads an available package from the repository!
Solution: Install ruby locally and configure Chinese data source, redownload fpm package, and finally use a symbolic link to link fpm, re-execute the packaging command to resolve this issue)
sudo apt-get install ruby-full
gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
gem sources -l
sudo gem install fpm
cd ~/.cache/electron-builder/fpm/fpm-1.9.3-2.3.1-linux-X86_64/ # version may differ, adjust according to actual situation
rm -rf fpm
ln -s /usr/local/bin/fpm fpm

3: Application crashes or errors after packaging

Crash

bash

# Normal in dev mode, but crashes after packaging
1. Check the log for errors
2. Run the program in cmd/terminal to see if there are any runtime exceptions after packaging (not in the log)
For example: d:/soft/electron-egg.exe  press "Enter"

Error 1: bytecode, strict encryption must be platform-specific; for example, win64 can only build 64-bit software, not 32-bit. As shown below, 32-bit software built with win64 cannot run.

javascript

A JavaScript error occurred in the main process
Uncaught Exception:
Error:[egg-core] load file:C:\Program Fileslee\resources\app.asar\public\electron\config config.defaultjsc,
error:Invalid Or incompatible cached data(cachedDataRejected)
at Object.Module.extensions. <computed>[as .jsc](C\Program Filesleelresourceslapp.asar\node.modules\bytenode\lib\indexjs:272:11)
at Module.load(internal/modules/cjs/loaderjs:935:32)
at Module.load(internal/modules/cjs/loaderjs:776:14)
at Function.f.load(electron/js2c/asar bundlejs:5:12913)
at Module.require (internal/modules/cjs/loaderjs:959:19)
at require(internal/modules/cjs/Herpers.js:88:18)
at Object.loadFile(C:Program Fileslee\resources\app.asarlnode moduleslee-corelcore\lib\utils\indexjs:29:19)
at AppLoader.requireFile(C:Program Filesleelresourceslapp.asarlnode moduleslee-corelcoreliblloaderlee loaderj.:23)
at AppLoaderloadFile(C:\Program

Error 2: Windows firewall, authorize electron application to access the network You may need to restart the computer

javascript

A JavaScript error occurred in the main process
Uncaught Exception:
Error: net::ERR CONNECTION REFUSED at SimpleURLLoaderWrapper.<anonymous> (electron/js2c/browser init.js:105:7068)

Error 3: Encryption module error

Reason: bytenode has differentiated support for Electron versions.

Solution: Please adjust the Electron version or bytenode version.

javascript

A JavaScript error occurred in the main process
Uncaught Exception:
Error: Cannot find module xxx
Require stack:
- xxxx/node_module/bytenode/lib/index.js

Error 4: Module not found

javascript

Uncaught Exception:
Error Cannot find module 'semver'
- xxx ....../resources/app.asar/.../index.js

Reason: Used non-official package managers such as yarn, cnpm, etc.

Solution: Please use npm.

4: CMD console garbled text

Reason: Windows terminal issue.

Solution:

Specify encoding in ./package.json

json

  "scripts": {
    "dev": "chcp 65001 && ee-bin dev",
    "start": "chcp 65001 && ee-bin start",
  }

5: npm package missing or abnormal

When installation is abnormal, delete node_modules and package-lock files

bash

# 1. For example: cannot find module 'debug'

Solution: npm install debug --save

# 2. When npm install is abnormal
Delete package-lock.json
Delete node_modules folder
Re-execute npm install or cnpm install

# Note
For package issues, always use npm for installation, do not use cnpm, pnpm, yarn

6: White Screen

bash

# White screen after packaging
Possible cause 1: Frontend base path
In the frontend project configuration, change the base path to relative path './'

Possible cause 2: Frontend routing
The frontend project routing uses history mode, change it to hash mode.

Reference: Why can't you use a proxy?

7: Installing better-sqlite3 fails

Different node.js versions correspond to different better-sqlite3 versions

bash

# error 1
......
env: python: No such file or directory
make: *** [Release/sqlite3.a] Error 127
rm ba23eeee118cd63e16015df367567cb043fed872.intermediate
gyp ERR! build error 
gyp ERR! stack Error: `make` failed with exit code: 2
gyp ERR! stack     at ChildProcess.onExit (/Users/apple/.nvm/versions/node/v14.16.0/lib/node_modules/npm/node_modules/node-gyp/lib/build.js:194:23)
......

# Reason
Requires Python environment (macOS higher versions no longer provide default Python)

# Solution
For Mac systems (other systems please search for Python installation methods)
1. brew install python@3.9
2. vim ~/.zshrc add
# python
alias python='/usr/local/bin/python3'
export PATH="/usr/local/opt/python@3.9/libexec/bin:$PATH"
3. source ~/.zshrc

bash

# error 2
......
gyp ERR! build error 
gyp ERR! stack Error: `C:\Program Files (x86)\MSBuild\14.0\bin\MSBuild.exe` failed with exit code: 1
gyp ERR! stack     at ChildProcess.onExit (C:\nvm\v14.16.0\node_modules\npm\node_modules\node-gyp\lib\build.js:194:23)
gyp ERR! stack     at ChildProcess.emit (events.js:315:20)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:277:12)
gyp ERR! System Windows_NT 10.0.19041
gyp ERR! command "C:\\Program Files\\nodejs\\node.exe" "C:\\nvm\\v14.16.0\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js" "rebuild" "--release"
gyp ERR! cwd D:\www\xing\oschina-desktop\node_modules\better-sqlite3
......

# Reason
Requires node-gyp tool

# Solution
Execute command: npm i node-gyp -g

bash

# error 3
......
was compiled against a different Node.js version using
NODE_MODULE_VERSION 83. This version of Node.js requires
NODE_MODULE_VERSION 89. Please try re-compiling or re-installing
......

# Reason
The sqlite package is written in C/C++, and the downloaded executable may not be compatible with your operating system, so it needs to be rebuilt from source code.

# Solution
Execute command: npm run re-sqlite

bash

# error 4
......
Error: node-gyp failed to reuild ......electron-edge-js
Error: ...BuildTools\MSBuild\15.0\Bin\...
......

# Reason
Missing Microsoft build tools

# Solution
Execute command: npm --vs2015 i -g --production windows-build-tools

bash

# error 5
......
Error: Could not detect abi for version 39.2.6 and runtime electron.  
Error: Updating "node-abi" might help solve this issue if it is a new release of electron ...
......

# Solution
Update node-abi
Execute command: npm install node-abi@latest --save-dev

# Other errors
See better-sqlite3 documentation (Troubleshooting installation)
https://github.com/WiseLibs/better-sqlite3/blob/2194095aa1183e9c21d28eafadeac0d4d4d42625/docs/troubleshooting.md

8: Opening the Vue dev server address (http://localhost:8080) in a browser shows an error

bash

Error: Uncaught TypeError: window.require is not a function......
Reason: The Vue project has a demo feature that needs to access the Electron module, which cannot be parsed in a regular browser.
Solution: Try to debug frontend pages in the Electron-launched window as much as possible.

9: Node module version mismatch

bash

# Error
......
was compiled against a different Node.js version using
NODE_MODULE_VERSION 83. This version of Node.js requires
NODE_MODULE_VERSION 89. Please try re-compiling or re-instaling
......

# Reason
Some npm packages are written in C/C++ and other languages. The downloaded executable may not be compatible with your operating system, so it needs to be rebuilt from source code.

# Solution
electron-rebuild -f -w module_name

10: Auto-update fails on macOS

bash

// Try disabling the asar feature
1. Check and confirm the Apple signing account
2. Modify the asar property value in the build object of package.json to false
3. Use the code encryption feature to prevent source code exposure

11: Software black screen or freeze

javascript

Error: ... ERROR:gpu_memory_buffer_support_x11.cc......
Reason: Win7 or Linux systems do not support GPU acceleration
Solution: Disable hardware acceleration in the ready() method of main.js
Pseudocode:
const isWin7 = os.release().startsWith('6.1');
const isLinux = true;
if (isWin7 || isLinux) {
  app.disableHardwareAcceleration();
}

12: Error when running encrypt

Issue 1:

javascript

env: node\r: No such file or directory
error Command failed with exit code 127.

Reason: Windows system line endings use CRLF, while Unix-like systems use LF.

Solution:

javascript

// Open with VS Code and change the line ending sequence from CRLF to LF
node_modules/ee-bin/index.js
node_modules/ee-core/bin/tools.js

Issue 2:

javascript

error Cannot find module 'node:assert/strict'
- xxx ....../electron-egg/node_modules/bytenode/lib/index.js
- xxx ....../electron-egg/node_modules/ee-bin/tools/encrytp.js

Reason: bytenode module bug

Solution:

javascript

// Install a specific version v1.3.6
npm uninstall bytenode
npm install bytenode@1.3.6

14: Ignore SSL certificate errors

javascript

ERROR:ssl_client_impl.cc(983) handshake failed; returned -1, SSL error code 1, net_error

Reason: The developer may have loaded an insecure address.

Solution:

javascript

// Lifecycle file electron/index.js
const {app: electronApp} = require("electron");

  async ready () {
    electronApp.commandLine.appendSwitch('ignore-certificate-errors');
  }

15: No latest.yml generated during auto-upgrade

Solution:

Add the following in ./config/builder.js

javascript

    "nsis": {
      "oneClick": false,
      ......
      ......
    },
    // Add this code section
    "publish": [
      {
        "provider": "generic",
        "url": ""
      }
    ],

16: API 404, cross-origin issues

Reason: For security, Electron does not allow cross-origin requests by default. When the frontend sends HTTP requests to access other services' APIs, it will throw an error. Or, it may show an API 404 error.

Solution:

javascript

// Using proxy mode causes the API to not be found

Solution:
1: Switch from proxy mode to environment variable mode. For example: define multiple URL variables in .env files (development, production) and assign values, then use environment variables for URL addresses in the code.
2: Set windowsOption.webPreferences.webSecurity=false in config.default.json
3: Disable same-origin policy
./electron/index.js
async ready () {
  // const { app: electronApp } = require("electron");
  electronApp.commandLine.appendSwitch("disable-web-security");
}

17: arm64 packaging error

Build module issue, please read carefully: issue#I8H21P

18: Terminal shows devtools error

Reason: Electron high version bug, does not affect functionality, and the official team has not fixed it...

javascript

[44354:0114/155817.742023:ERROR:CONSOLE(1)] "Request Autofill.enable failed. {"code":-32601,"message":"'Autofill.enable' wasn't found"}", source: devtools://devtools/bundled/core/protocol_client/protocol_client.js (1)
[44354:0114/155817.742071:ERROR:CONSOLE(1)] "Request Autofill.setAddresses failed. {"code":-32601,"message":"'Autofill.setAddresses' wasn't found"}", source: devtools://devtools/bundled/core/protocol_client/protocol_client.js (1)

19: Startup error on Linux system

Error content:

javascript

Fatal:electron_main_delegate.cc(253)] Running as root without --no-sandbox is not supported。

Reason: Operating system protection mechanism, root does not have sandbox.

Solution:

Switch to a regular user
Find other solutions online.

20: path module argument error

Error content:

javascript

TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received type undefined

Reason: Node.js require() module import is synchronous. Do not directly use ee-core APIs at the module top level, because the framework has not finished initializing at that point.

Solution:

Only import ee-core APIs at the top level, do not directly use/call their methods.

21: Frontend error

Error content:

javascript

error when starting dev server:
TypeError: crypto$2.getRandomValues is not a function
    at resolveConfig (.../electron-egg/node_modules/vite/dist/node/chunks/dep-c8b7c7d0.js:10807:17)

Reason: Node.js version and Vite version mismatch.

Solution:

Upgrade Node.js or downgrade the Vite version.

Config

Frontend Module

Communication

Database

Tasks

go

java

python

Frequently Asked Questions

1: Download resources timeout during packaging

2: Packaging failure (exception)

3: Application crashes or errors after packaging

4: CMD console garbled text

5: npm package missing or abnormal

6: White Screen

7: Installing better-sqlite3 fails

8: Opening the Vue dev server address (http://localhost:8080) in a browser shows an error

9: Node module version mismatch

10: Auto-update fails on macOS

11: Software black screen or freeze

12: Error when running encrypt

14: Ignore SSL certificate errors

15: No latest.yml generated during auto-upgrade

16: API 404, cross-origin issues

17: arm64 packaging error

18: Terminal shows devtools error

19: Startup error on Linux system

20: path module argument error

21: Frontend error

Frequently Asked Questions ​

1: Download resources timeout during packaging ​

2: Packaging failure (exception) ​

3: Application crashes or errors after packaging ​

4: CMD console garbled text ​

5: npm package missing or abnormal ​

6: White Screen ​

7: Installing better-sqlite3 fails ​

8: Opening the Vue dev server address (http://localhost:8080) in a browser shows an error ​

9: Node module version mismatch ​

10: Auto-update fails on macOS ​

11: Software black screen or freeze ​

12: Error when running encrypt ​

14: Ignore SSL certificate errors ​

15: No latest.yml generated during auto-upgrade ​

16: API 404, cross-origin issues ​

17: arm64 packaging error ​

18: Terminal shows devtools error ​

19: Startup error on Linux system ​

20: path module argument error ​

21: Frontend error ​

Frequently Asked Questions

1: Download resources timeout during packaging

2: Packaging failure (exception)

3: Application crashes or errors after packaging

4: CMD console garbled text

5: npm package missing or abnormal

6: White Screen

7: Installing better-sqlite3 fails

8: Opening the Vue dev server address (http://localhost:8080) in a browser shows an error

9: Node module version mismatch

10: Auto-update fails on macOS

11: Software black screen or freeze

12: Error when running encrypt

14: Ignore SSL certificate errors

15: No latest.yml generated during auto-upgrade

16: API 404, cross-origin issues

17: arm64 packaging error

18: Terminal shows devtools error

19: Startup error on Linux system

20: path module argument error

21: Frontend error