How To

ForgeRock Identity Platform

Does not apply to Identity Cloud

How do I troubleshoot issues with source code and ForgeRock Maven repositories?

Last updated Mar 29, 2023

The purpose of this article is to provide advice on troubleshooting issues with source code (Git repositories) and the ForgeRock Maven repositories. The Apache Maven™ repositories are password-protected repositories that hold the binaries required to build ForgeRock products (AM, DS, IDM and IG) and compile custom code.

1 reader recommends this article

Overview

The terms source code and Maven repositories are sometimes used interchangeably, which isn't strictly accurate. You can read more about them here: Understanding source code access for ForgeRock products but in summary:

Source code

Source code for commonly customized areas of ForgeRock products is hosted in the Git repositories. Working with source code (for example, cloning Git repositories to build and customize ForgeRock code) also requires access to the binaries in our Maven repositories.

Maven repositories

The ForgeRock Maven repositories host the binaries for the ForgeRock Identity Platform. You may require access to these binaries when you are compiling custom code.

The Maven repositories are password protected and you must authenticate in order to access them. This is achieved via the ~/.m2/settings.xml file and the process to create this file is described in How do I access the ForgeRock protected Maven repositories?

Note

You must have a valid ~/.m2/settings.xml file in order to do anything with ForgeRock binaries and source code.

Issues can arise with accessing the Maven repositories and/or building source code, but regenerating the ~/.m2/settings.xml file is often a good first troubleshooting step. If this doesn't work, proceed to one of the following sections as needed:

Issues with accessing the Maven repositories
Issues with building from source

Issues with accessing the Maven repositories

If you are experiencing issues accessing the Maven repositories, you should check the following statements are all true and resolve if not:

Statement	Resolution
The Backstage account you are using has been added to a subscription.	Ask your subscription administrator to add the Backstage account to the subscription. Administering Subscriptions
The email address associated with your Backstage account has been verified. You must reverify your email address on a yearly basis.	Verify your email address in Backstage. You can check whether your email address has been verified or not on the Profile page in Backstage. Logging in to ForgeRock services
You have logged into Artifactory using your Backstage username and password.	Log into Artifactory.
You have generated a ~/.m2/settings.xml file using your Backstage username and password. You logged into Artifactory before generating the ~/.m2/settings.xml file. You used curl to generate the ~/.m2/settings.xml file. You have used your username not your email address. You have generated the file recently (more recently than February 24, 2022)	Regenerate your ~/.m2/settings.xml file using curl with your Backstage username. How do I access the ForgeRock protected Maven repositories?
You have added any required dependency repositories to the ~/.m2/settings.xml file. Dependency repositories are needed when: You are building custom code (for all products and versions). You are building a pre-ForgeRock Identity Platform 6.5 version.	Add dependency repositories to your ~/.m2/settings.xml file or regenerate the file. How do I access the ForgeRock protected Maven repositories?
You have added any required mirrors to the ~/.m2/settings.xml file. Mirrors need to be declared when you are using Maven 3.8.1 or later.	Add all required mirrors to your ~/.m2/settings.xml file. Blocked mirror for repositories error when building from source using Maven 3.8.1 or later

Statement

Resolution

The Backstage account you are using has been added to a subscription.

Ask your subscription administrator to add the Backstage account to the subscription.

Administering Subscriptions

The email address associated with your Backstage account has been verified.

You must reverify your email address on a yearly basis.

Verify your email address in Backstage. You can check whether your email address has been verified or not on the Profile page in Backstage.

Logging in to ForgeRock services

You have logged into Artifactory using your Backstage username and password.

Log into Artifactory.

You have generated a ~/.m2/settings.xml file using your Backstage username and password.

You logged into Artifactory before generating the ~/.m2/settings.xml file.
You used curl to generate the ~/.m2/settings.xml file.
You have used your username not your email address.
You have generated the file recently (more recently than February 24, 2022)

Regenerate your ~/.m2/settings.xml file using curl with your Backstage username.

How do I access the ForgeRock protected Maven repositories?

You have added any required dependency repositories to the ~/.m2/settings.xml file. Dependency repositories are needed when:

You are building custom code (for all products and versions).
You are building a pre-ForgeRock Identity Platform 6.5 version.

Add dependency repositories to your ~/.m2/settings.xml file or regenerate the file.

How do I access the ForgeRock protected Maven repositories?

You have added any required mirrors to the ~/.m2/settings.xml file. Mirrors need to be declared when you are using Maven 3.8.1 or later.

Add all required mirrors to your ~/.m2/settings.xml file.

Blocked mirror for repositories error when building from source using Maven 3.8.1 or later

Issues with building from source

If your build fails, you should:

Verify you are using an up-to-date ~/.m2/settings.xml file.
- If you are not sure, you should regenerate it per How do I access the ForgeRock protected Maven repositories? and copy it to the ~/.m2 directory.
For the am-external Git repository:
- Ensure you are accessing it via GitHub (not Bitbucket).
- Ensure you are using https to clone it (not ssh), for example:$ git clone https://github.com/ForgeRock/am-external.git
Ensure you have specified the appropriate dependency repository in your project's POM file.
- You must add a dependency repository if you are building custom code for any version or building a pre-ForgeRock Identity Platform 6.5 version. See How do I access the ForgeRock protected Maven repositories? for further information.
Review the common error messages below.
Check the JAVA_HOME variable has been set correctly using the following command: $ echo $JAVA_HOME
Check you are using the correct JDK and Maven versions for your build (for AM, refer to the Dependencies table below). You can check these versions using the following commands: $ java --version $ mvn --version
AM only: Ensure the groupIds in the pom.xml are correct; they should equal org.forgerock.am, for example: <groupId>org.forgerock.am</groupId>The groupIds in older versions of AM were org.forgerock.openam.
If all the above is correct and your build still fails, it is likely that network issues are to blame, for example, you have a firewall that is preventing the build from calling out to the repository.

Common errors

Error message	Details
You do not have permission to access Bitbucket.	The `am-external` Git repository moved to GitHub (from Bitbucket). You can resolve this error by using GitHub to access the am-external Git repository. Ensure you use https to clone it (not ssh), for example:$ git clone https://github.com/ForgeRock/am-external.git
Blocked mirror for repositories	Maven 3.8.1 removed support for accessing Maven repositories over HTTP; pre-7.1 releases in the ForgeRock Maven repositories use HTTP, which means they won't build using Maven 3.8.1 or later. You can resolve these errors by adding mirror repositories (using mirrorOf) to the ~/.m2/settings.xml file to redirect the mirrors to HTTPS as explained in Blocked mirror for repositories error when building from source using Maven 3.8.1 or later
Failed to execute goal org.apache.maven.plugins:maven-enforcer-plugin:1.4:enforce (enforce-java-version) on project [project_name]-bom: Execution enforce-java-version of goal org.apache.maven.plugins:maven-enforcer-plugin:1.4:enforce failed: An API incompatibility was encountered while executing org.apache.maven.plugins:maven-enforcer-plugin:1.4:enforce: java.lang.ExceptionInInitializerError: null	An incompatible version of Java is being used or the JAVA_HOME variable is not set. You can resolve this error by ensuring the JAVA_HOME variable is set to a compatible Java version. If you are using the Bazel build tool, you should ensure you are using the latest Java update for the specified Java version.
Failed to collect dependencies at external:jdmkrt:jar:1.0-b2 Failed to collect dependencies at external:jdmktk:jar:1.0-b2 Failed to collect dependencies at external:jdmkrt:jar:2007-01-10	ForgeRock is not licensed to redistribute the OpenDMK library. This error means the jdmkrt.jar or jdmktk.jar binary, which is contained in this library is missing. You can resolve these errors by setting up the OpenDMK library as explained in How do I set up the OpenDMK library for building AM or DS from source?
Non-resolvable parent POM authentication failed 401 Unauthorized Non-resolvable import POM Not authorized	A major Artifactory (maven.forgerock.org) upgrade in February 2022 changed the way passwords are encrypted. You can resolve these errors by regenerating the ~/.m2/settings.xml file as detailed in How do I access the ForgeRock protected Maven repositories?
Failed to execute goal on project [project_name]: Could not resolve dependencies for project [project_name]: Could not [find/transfer] artifact org.apache.servicemix.bundles:org.apache.servicemix.bundles.java-xmlbuilder:bundle:1.1_1	AM 7 and later: The `org.apache.servicemix.bundles:org.apache.servicemix.bundles.java-xmlbuilder` dependency is missing from your Maven repository and cannot be retrieved using the default project configuration. You can resolve this error by updating the project's POM file as detailed in Building AM 7.x projects from source fail with a Failed to execute goal error
FAILURE! org.testng.TestException: The exception was thrown with the wrong message: expected	Some error messages are hard-coded in English. When Maven attempts to display them in a different language (as determined by your system locale), it fails and generates this exception. You can resolve this error as explained in Building from source fails with The exception was thrown with the wrong message when system locale is not English
Non-resolvable import POM: Could not transfer artifact org.forgerock.commons:commons-bom:pom	AM 6.5.x: The required version specific dependency repositories are not declared in your ~/.m2/settings.xml file. You can resolve these errors by regenerating the ~/.m2/settings.xml file as detailed in How do I access the ForgeRock protected Maven repositories?

Dependencies

You should use Git 1.7.6 or above, and build with the appropriate JDK version and Maven depending on your version of AM:

Version	JDK version	Maven version
AM 7.2 and later	11	3.6.0 or later
AM 7 and 7.1	11	3.3.0 or later
AM 6.5.5	8 or 11	3.6.0 or later
AM 6.5, 6.5.1, 6.5.2, 6.5.3 and 6.5.4	8 or 11	3.3.0 or later
AM 6	8	3.3.0 or later

If you are using the Bazel build tool, you should ensure you are using the latest Java update for the specified Java version as well as the latest Maven version.