Skip to main content

Resolve App Studio build failures related to Node.js, npm, or SSL configuration

Updated

Goal

Troubleshoot and resolve build-time failures in App Studio Enterprise installations when errors occur related to missing dependencies, SSL network restrictions, or unsupported Node.js/npm versions.

 

Environment

  • Fusion 4.x (including 4.2.6 SP3)

  • App Studio Enterprise 4.14.0

  • Self-hosted environments

  • Network configurations involving corporate proxies or security platforms (e.g., Zscaler)

 

Guide

Confirm required dependencies

App Studio Enterprise requires specific versions of key dependencies. Ensure the following are installed on the build machine:

  • Java: 1.8

  • Node.js: 16.17.0

  • npm: 9.2.0

Note: These versions are required due to deprecated dependencies in the App Studio build toolchain. More recent versions may cause build failures.

If your system prevents installation of unsupported or legacy versions due to policy constraints, App Studio may not be compatible without significant manual adjustments.

Check for missing npm installation

A common error:

Cannot run npm, no such file or directory

indicates that npm is not in the system path. To resolve:

  • Ensure both Node.js and npm are installed

  • Verify npm is accessible via echo $PATH or which npm

Bypass OpenSSL-related runtime errors

For Node.js versions >= 17, OpenSSL 3.0 may cause startup errors such as:

Error: error:0308010C:digital envelope routines::unsupported

If your package.json uses the following:

"start": "react-scripts start"

Modify it to:

"start": "react-scripts --openssl-legacy-provider start"

 

If your start script differs (e.g., uses webpack:watch), this workaround may not apply. App Studio 4.14.0 does not always use react-scripts.

Validate network and SSL configuration

If your organization uses proxy services such as Zscaler:

  • Confirm with network administrators that SSL inspection is not blocking Maven or npm registry requests.

  • Temporarily bypass or whitelist the build system for outbound requests during installation if possible.

Build-time SSL errors often stem from intercepted or untrusted certificates during package downloads.

Inspect deprecated or unavailable dependencies

If the build proceeds but fails later with deprecation warnings or missing packages:

  • These may be unavoidable due to outdated upstream package versions.

  • Lucidworks has not yet updated App Studio 4.x to support newer npm/node versions.

If required packages are no longer available, rebuilding App Studio may not be feasible on modern environments without workarounds such as using isolated containers with legacy toolchains.

Alternatives and workarounds

If using older dependencies is not permitted:

  • Consider building App Studio inside a Docker container configured with supported versions of Node.js, npm, and Java.

  • Contact Lucidworks Support to request updates on newer versions of App Studio that support updated Node/npm toolchains.

 

Additional notes

  • App Studio Enterprise for Fusion 4.x is no longer actively updated to support recent dependency upgrades.

  • Future compatibility will require upgraded Fusion versions or containerized legacy environments.

 

Additional assistance

If the issue persists after applying the workarounds above, contact the Lucidworks Support Team and share:

  • The full package.json

  • The exact Node.js and npm versions

  • Complete build logs

This will assist the support team in determining the most viable path forward.

 
 
 

 

 

 

Powered by Zendesk