How can I resolve common development issues on Electron?

This page outlines common challenges encountered throughout the integration, compilation, execution, and packaging phases of Electron SDK app development. It offers potential solutions to address these issues effectively.

Error message: code ETIMEDOUT

This issue is usually caused by a network or proxy problem. Try one of the following solutions:

• Set a mirror source

  https://registry.npmjs.org/ is the original official npm mirror download address which is slow for domestic users. Switching to a reliable mirror source can improve the download speed:

  
  

  _4

  # Set npm mirror source to Taobao source

  _4

  npm config set registry https://registry.npmmirror.com/

  _4

  # Set npm Electron mirror source as a Taobao mirror source

  _4

  npm config set ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/

  
  

• Set up the proxy correctly

  If you are using a network proxy, make sure that the proxy settings for the command line tool are correct:

  
  

  _6

  # View Global Proxy Address

  _6

  npm config get proxy

  _6

  # Set the global proxy (HTTP proxy address)

  _6

  npm config set proxy http://<proxy-server-address>:<port-number>

  _6

  # Set the global proxy (HTTPS proxy address)

  _6

  npm config set proxy https://<proxy-server-address>:<port-number>

  
  

  Typically, the proxy tool offers a convenient one-click copy command for configuring the terminal proxy settings.

• Modify environment variables

Windows

Right click on Computer > Properties > Advanced System Settings > Environment Variables. Create the following variable under user variables:

variable name	variable
ELECTRON_MIRROR	https://npmmirror.com/mirrors/electron/

Once the setup is complete, reopen a command line tool and run npm install to install the dependencies.

macOS

Run the following command in a terminal to modify the environment variables:

export ELECTRON_MIRROR='https://npmmirror.com/mirrors/electron/'
export ELECTRON_GET_USE_PROXY=true

Note

Environment variables modified using this method take effect in the current terminal only. If you want the variables to take effect permanently, configure these in .zshrc or .bashrc.

In this case, Agora recommends that you first refer to npm install is slow or times out. Use npm native commands to set the mirror source and proxy address, and then install the dependencies.

Refer to the following commands to set up the proxy and mirror source for yarn:

_7

# Set up a proxy

_7

yarn config set proxy <proxy-server-address>:<port-number>

_7

yarn config set https-proxy <proxy-server-address>:<port-number>

_7

_7

# Set the mirror source

_7

yarn config set registry https://registry.npmmirror.com/

_7

yarn config set ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/

Error message: Too many levels of symbolic links error

The error indicates that there are too many layers of symbolic links (also called soft links) in the project, and there may be circular dependencies that prevent the library from being installed.

Use the following command to prevent symbolic links from being created when installing npm packages:

_1

npm install --no-bin-links

• Obtain from the release notes: The SDK version number listed in the release notes is identical to the Native version number.

• Obtain from the demo: The version number of Native SDK is shown directly at the bottom of the Electron demo as shown in the following figure:

  

Error message: agora_node_ext.node is not a valid Win32 application

By default, npm downloads the native module for the current computer architecture when installing dependencies.

This error means that the wrong architecture module was retrieved during the dependency download, resulting in the application being unable to start. It suggests that a 32-bit agora_node_ext.node is required.

Try one of the following methods to fix the issue:

• Use npm environment variables

  Create a new .npmrc file directly in the root directory of your project and write the following to configure the npm environment variables:

  
  

  _2

  agora_electron_sdk_arch = ia32

  _2

  arch=ia32

  
  

  After saving the configuration, reinstall agora-electron-sdk and try to package it again.

• Manually configure agora_electron in package.json

  Configure agora_electron with the following fields:

  • platform: (Optional) The default is selected according to the system. For example, macOS is darwin, Windows is win32.
  • prebuilt: (Optional) Set to true by default to prevent compatibility issues with Electron or Node.js versions that are incompatible with the SDK.
  • arch: (Optional) Selected by default according to the system architecture.

  For example, if you want to package a 32-bit application on a Windows 64-bit computer, configure package.json as follows:

  
  

  _4

  "agora_electron":{

  _4

  "platform":"win32",

  _4

  "arch":"ia32"

  _4

  }

  
  

  After saving the configuration, reinstall agora-electron-sdk and try to package it again.

If you encounter the problem that the application window cannot be obtained through getScreenWindowsInfo which prevents you from sharing the screen, refer to the following steps to troubleshoot:

1. Confirm that the API call is correct

   Refer to the following documentation to check that the screen sharing related API calls are correct:

   • Electron screen sharing demo source code

2. Check for authorization

   Refer to the Official Electron documentation to make sure that screen sharing permissions have been granted.

3. Contact Agora support to troubleshoot

   If the previous steps do not solve the problem, contact Agora technical support.

Packaging crashes with a message similar to the following:

If you encounter this problems, check the following:

1. Check if the file in the error message exists. For example, in the figure, AgoraRtcwrapper cannot be found.

2. Check if webpack.config is configured correctly.

   Make sure that the syntax of the webpack.config file is correct and matches the requirements of your project. Refer to the official webpack documentation for details.

3. Check if the asar.unpacked configuration is correct.

   The asar.unpacked configuration is used to specify which files should be unpacked into the application package. Refer to the configuration in the demo, or check the Electron official documentation.

4. Ensure that you use require for your project's dependency on the SDK.

   On macOS, using import statements may result in symbol conflict issues that lead to packaging failures. To avoid this, use require statements instead. This is particularly relevant for projects using the Vue framework, as they are prone to packaging failures.

   
   

   _3

   // import changed to require

   _3

   // import createAgoraRtcEngine from 'agora-electron-sdk';

   _3

   const createAgoraRtcEngine = require("agora-electron-sdk");

   
   

Error message: com.apple.security.app-sandbox of null

This error indicates an app-sandbox exception. app-sandbox is a security mechanism that restricts an application's access to system resources.

Check that the .entitlements file is configured correctly to ensure that there are no syntax and naming errors. If you don't need to publish your app to the App Store, remove com.apple.security.app-sandbox from the .entitlements.

Error message: Uncaught SyntaxError:Error parsing

This error appears when the configuration of asar.unpacked, which is used to specify which files should be unpacked into the application package, is incorrect. Refer to the configuration in the demo, or check the official Electron documentation for details.

The following errors indicate that the library could not be parsed or the module could not be found.

• failed to compile, can't resolve agora-electron-sdk

• failed to compile, can't resolve agora_node_ext

• cannot find module

The error is usually caused by incorrect configuration of the compilation tool. Refer to the following methods to solve the problem:

1. If your project uses Vue, make sure that you use require, not import.

   
   

   _3

   // modify import to require

   _3

   // import createAgoraRtcEngine from 'agora-electron-sdk';

   _3

   const createAgoraRtcEngine = require("agora-electron-sdk");

   
   

2. Modify tool configuration

   Depending on the language you are using and the compilation tool, refer to the following pages for configuration:

   • Vue：https://nklayman.github.io/vue-cli-plugin-electron-builder/
   • Vite：https://electron-vite.github.io/
   • React：https://github.com/electron-react-boilerplate/electron-react-boilerplate
   • Webpack：https://webpack.electron.build/