Issue
After upgrading to CloudBees CI 2.528.1.29783 or later, an HA (active/passive) controller with a custom $JENKINS_HOME/jgroups.xml fails to start with the following error:
java.lang.Exception: JGRP000002: unable to load protocol com.cloudbees.jenkins.ha.singleton.CHMOD_FILE_PING at org.jgroups.stack.Configurator.createLayer(Configurator.java:...) at org.jgroups.stack.Configurator.createProtocols(Configurator.java:...) at org.jgroups.stack.Configurator.setupProtocolStack(Configurator.java:...) ... at com.cloudbees.jenkins.ha.singleton.HASingleton.start(HASingleton.java:...) Caused: java.lang.Error: Failed to form a cluster at com.cloudbees.jenkins.ha.singleton.HASingleton.start(HASingleton.java:...)
A related failure can also occur if the JGroups shared directory is not writable by the Jenkins service user:
com.cloudbees.jenkins.ha.singleton.JGroupsSafeFilePing$JenkinsHAInitException: JGROUPS file location exists but is not writable
Environment
-
CloudBees CI on traditional platforms - client controller 2.528.1.29783 or later
-
CloudBees CI on traditional platforms - operations center 2.528.1.29783 or later
-
Instances using a custom
$JENKINS_HOME/jgroups.xml
Explanation
Starting with CloudBees CI 2.528.1.29783, a security fix hardened the JGroups shared folder so that it is no longer world-writable by default.
As part of this change, the protocol class com.cloudbees.jenkins.ha.singleton.CHMOD_FILE_PING was removed and replaced by com.cloudbees.jenkins.ha.singleton.JGroupsSafeFilePing.
If a custom $JENKINS_HOME/jgroups.xml still references CHMOD_FILE_PING, the JGroups stack cannot load the protocol and the controller fails to form a cluster.
org.jgroups.protocols.FILE_PING (the upstream JGroups class) is not a valid substitute — it produces the same JGRP000002 error because it is not bundled in the CloudBees HA plugin.
|
Resolution
On all HA nodes, edit $JENKINS_HOME/jgroups.xml and replace the CHMOD_FILE_PING protocol element:
<!-- BEFORE (no longer valid in 2.528.1.29783+) --> <com.cloudbees.jenkins.ha.singleton.CHMOD_FILE_PING location="${HA_JGROUPS_DIR}" remove_old_coords_on_view_change="true"/>
with:
<!-- AFTER --> <com.cloudbees.jenkins.ha.singleton.JGroupsSafeFilePing location="${HA_JGROUPS_DIR}" remove_old_coords_on_view_change="true"/>
Then restart all HA nodes.
Prerequisite: directory permissions
The JGroupsSafeFilePing protocol enforces that ${HA_JGROUPS_DIR} is readable and writable by the Jenkins service user on every node (same UID/GID or shared group).
If this condition is not met, the controller will fail with:
com.cloudbees.jenkins.ha.singleton.JGroupsSafeFilePing$JenkinsHAInitException: JGROUPS file location exists but is not writable
Fix this by adjusting ownership or permissions on the shared directory:
sudo chown -R jenkins:jenkins ${HA_JGROUPS_DIR} sudo chmod 770 ${HA_JGROUPS_DIR}
Workaround
To restore service immediately while you work on updating jgroups.xml, add the Java argument -Dcom.cloudbees.jenkins.ha=false to one controller and restart it.
This disables High Availability, so only that single controller will be running.
Recommendation
For setups that only need port and timeout customization, consider migrating to the UI-managed HA configuration instead of maintaining a manual jgroups.xml:
This option is available in CloudBees CI 2.303.2.3 and later, and automatically handles protocol changes across upgrades.
See Upgrade guide for instances running High Availability previous to 2.249.2.3 for additional migration guidance.