AEM: Constraints on JCR code-based names (item/project)


The AEM CMS has certain constraints in terms of length or inclusion of some special characters in item or project names, and the AEM connector complies with those principles in the names of your items and projects which you send off for translation in XTM Cloud.

For this reason, you might sometimes come across a pretty generic error in the AEM CMS UI, informing you that the process for starting translation in XTM Cloud failed:


The next step you should take is to confirm that the issue might indeed be caused by the naming character constraints. For this purpose, browse through AEM logs. A great deal of logs are generated on the AEM side, so, if you contact the XTM International Support team for issue troubleshooting, you will probably be asked to supply relevant logs from your AEM instance, in the form of a file. This is especially true if the Support team does not have access to your server. Read the following article to find out how to extract logs: AEM: Where are logs located and what information do they contain?.

Details about JCR code-based character restrictions

One of the logs related to the naming character restriction looks like this:

Caused by: {"reason":"Incorrect parameters were passed.","incorrectParameters":"NAME_TOO_LONG"}

That is sometimes the reason the project cannot be started.

Since the AEM CMS is based on JCR codes, here is the most important information about the character constraints that this code imposes:

According to the JCR specification, the following characters are generally forbidden in JCR names:

  1. / (forward slash).

  2. : (colon) except as part of a namespace prefix.

  3. [ (left square bracket).

  4. ] (right square bracket).

  5. * (asterisk).

  6. ' (single quote).

  7. " (double quote).

  8. | (vertical bar).

  9. (space) Specifically, leading and trailing spaces are not allowed.

  10. Any control characters (ASCII characters in the range 0 to 31).

These restrictions help maintain consistency and avoid parsing errors or conflicts within the repository.

If you are dealing with node names or property names in JCR, it is important to ensure that they do not contain any of these forbidden characters. If you still need to include any of these characters, consider encoding or otherwise transforming the names to fit within the permitted character set.

For the most accurate and detailed information, refer to the specific version of the JCR specification you are working with or the documentation for the JCR implementation that you are using (e.g. Apache Jackrabbit). Jackrabbit Oak – Constraints.

The Java Content Repository (JCR) specification itself does not explicitly define a character limit for node names or property names. However, practical limitations might be imposed by the specific implementation of JCR that you are using, as well as underlying storage systems and databases.

For instance, if you are using Apache Jackrabbit, which is a common implementation of JCR, the practical limits are influenced by several factors, including:

  1. Underlying Database Constraints: the database used to store the repository data might have its own limits on string lengths. For example, many relational databases have a limit of 255 characters for column names, which might affect property names.

  2. Path Length: the overall path length (including all node names in the hierarchy) can be constrained by the filesystem or database. This is less about individual name limits and more about the total length of the full path.

  3. Implementation-Specific Constraints: Jackrabbit or other JCR implementations might impose additional constraints for performance or other reasons. These constraints should be documented in the implementation's official documentation.

  4. Namespace and Node Name Length: while the JCR specification does not define a hard limit, it is advisable to keep node and property names within a reasonable length (typically under 255 characters), to avoid issues with various storage back-ends and to ensure good performance.

In the example shown above, the name was simply too long; hence the error.