controller fails to start after upgrading CloudBees Jenkins Enterprise with the error 'Contains a forbidden character'

Article ID:360038308612
2 minute readKnowledge base


After upgrading CloudBees Jenkins Enterprise (which uses Mesos/Marathon) to version 1.11.23, 1.11.24, or 1.11.25, controllers fail to start up with the error:

Error is invalid because: <div class=error><img src='/cjoc/static/59d37489/images/none.gif' height=16 width=1>Contains a forbidden character. Only digits (0-9), lowercase characters (a-z) and dashes (-) are allowed.</div>

This was caused by a change in the source code of the controller Provisioning plugin, which prevents controllers from being created with dots in the controller name, but it also causes this failure when you upgrade and already have a controller with dots in the name.


This is fixed in the CloudBees Jenkins Enterprise 1.11.26.

The recommended solution is to upgrade to 1.11.26 or later.


  1. Locate the backup for the controller that fails to start that was taken immediately before the upgrade was started. If you do not have one, take one manually following the steps in Backing up manually.

  2. Create a new controller that uses the same controller Docker image version, and all controller provisioning arguments (CPU shares, RAM, JVM arguments, ..) and ensure you use a name that does not have . characters in it.

  3. Install the Recommended plugins during the initial setup wizard.

  4. Create a Restore job on that new controller by following Restoring from backup (using a restore job)

  5. Configure that restore job to use a backup from the controller that cannot start (the one with the name that has a . in it).

  6. Run that restore job.

  7. Restart the controller so the restore takes effect.

  8. If you are using Role Based Access Control, and you have defined RBAC roles and groups at the controller level, you will need to migrate those to the new controller by accessing the JENKINS_HOME filesystem of the Operations Center, and copy the rbac xml section from the old controller’s configuration file at jobs/yourOldcontrollerName/config.xml to the new controller’s configuration file at jobs/yourNewcontrollerName/config.xml, and then restart the controller.

  9. Any jobs that trigger builds on a separate controller using the controller name would need to be updated, as well as any external scripts that call the Jenkins API or CLI using the controller name.

Affected product/plugin versions