DocumentationExperience Cloud KCS

Node.js and npm version support and compatibility for AEM front-end builds

Last update: July 7, 2026

AEM front-end modules (such as ui.frontend with React or Webpack) require a Node.js version compatible with the AEM build environment, and using an unsupported or mismatched version leads to Cloud Manager pipeline build failures or uncertainty when upgrading. To fix the issue, identify your deployment model, confirm your target Node.js and npm versions are supported, and set the correct version in your pipeline configuration.

Description description

Environment

  • Adobe Experience Manager as a Cloud Service
  • AEM Managed Services (AEM 6.5)
  • Adobe Experience Manager 6.5 (on-premise)

Issue/Symptoms

  • Cloud Manager pipeline builds fail when using an unsupported Node.js version (for example, using Node 20 before support was added).
  • Uncertainty about which npm version is bundled with a supported Node.js version (for example, npm 10.8.2 with Node 18, or npm 9.6.7 with Node 23.11.1).

Root cause

Different AEM deployment models handle Node.js differently. In AEM as a Cloud Service, Node.js is part of the Cloud Manager build container with validated versions. In AEM 6.5 Managed Services or on-premise, Node.js is purely a build-time dependency that you manage, and no official support matrix exists. Attempting to use versions not yet released in Cloud Manager, or mismatched npm versions, can cause build incompatibilities.

Steps to reproduce

  1. Identify your deployment model: AEM as a Cloud Service, AEM 6.5 Managed Services, or AEM 6.5 on-premise.
  2. For AEM as a Cloud Service, run node -v and npm -v in a pipeline build step and review the printed versions in the build logs.
  3. Compare your target Node.js version against the officially supported version list.

Resolution resolution

To fix the issue, identify your AEM deployment model, then follow the steps for your environment:

For AEM as a Cloud Service

  1. Verify that your target Node.js version is supported. Per the official documentation, the supported major versions are 12, 14, 16, 18, 20, 22, and 23. Cross-check against the Experience League supported list.
  2. Confirm the npm version bundled with your Node.js version. Run node -v and npm -v in a Cloud Manager pipeline build step and review the logs (for example, Node 18 bundles npm 10.8.2, and Node 23.11.1 bundles npm 9.6.7). If npm reports a 404 for its version, that reflects public registry differences, so confirm the actual bundled version.
  3. Configure the Node.js version in your pipeline. In Cloud Manager, go to Environments > Configuration > Environment Variables and set CM_CUSTOM_VAR_NODE_VERSION (or NODE_VERSION where applicable). Re-run the pipeline and confirm the Node version in the logs, ensuring no conflicting version is defined in pom.xml or your build script.
  4. For full-stack pipelines, set NODE_VERSION to 20 to use Node.js 20, and validate your project dependencies for Node 20 compatibility.
  5. Use Node.js 22 or 23 only where documented support exists. If a front-end build fails, revert to Node 18 or 20 and test dependency compatibility.
  6. Validate third-party dependency compatibility by testing builds with the new Node.js version and confirming no front-end regressions. For vendor-specific issues, contact the third-party vendor directly, since Adobe cannot provide their compatibility details.
  7. Confirm the fix by running node -v and npm -v in the build logs and triggering a full pipeline execution to verify the ui.frontend build succeeds without version-mismatch errors.
  8. If builds still fail despite correct configuration, contact Adobe Support with your pipeline logs, pom.xml, package.json, and Cloud Manager environment variable list.

For AEM 6.5 (Managed Services and on-premise)

  1. Note that there is no official Node.js support matrix for AEM 6.5. Node.js is customer-managed, used only for build-time tooling, and decoupled from the AEM runtime.
  2. When updating Node.js and npm, keep package.json and pom.xml consistent so that local and CI builds align (for example, upgrading Node 12.22.7 to 16.17.0 and npm 6.14.0 to 8.15.0).
  3. Confirm the versions by running node -v and npm -v locally and in CI, and verify the front-end build completes without version-mismatch errors.
  4. If confusion or build issues remain, contact Adobe Support with your build script details, pom.xml, and package.json.
recommendation-more-help
experience-cloud-kcs-help-kbarticles