Saturday, April 25, 2009

JCR troubleshooting topic: troubleshooting common exceptions

You need to troubleshoot JCR (Java Content Repository) error codes that appear in the logs of your IBM Web Content Management (WCM) system.

JCR exceptions in logs

Resolving the problem
PathNotFound Exception and ItemNotFound exceptions

Within a workspace, each node is identified by its path and its uuid. In order to retrieve a node you must specify either its path or its uuid. The retrieval methods within the repository throw the exceptions "PathNotFoundException" and "ItemNotFoundException" to indicate that the node or property that you attempted to retrieve (either by path or uuid) does not exist in the current workspace. This exception is the repository's method of telling the WCM application that is does not have the item being requested.

NOTE: From the perspective of the API, both a node and a property possess a "path" which can be requested. Both Node and Property are sub-interfaces of the common parent interface Item, and hence the "ItemNotFoundException" notification.


Example: javax.jcr.nodetype.NoSuchNodeTypeException: Node Type clb:clbLibrary not found
This problem indicates that the application is expecting a JCR Node Type which has not been defined.

Two scenarios are known to lead to this problem.

1. The node types have not been defined during the Portal upgrade. This is the most common scenario, and occurs when either Portal update has failed, or was never correctly invoked. To resolve this problem, we need to find out what happened during Portal update, and why the node types were not created correctly at this time.
2. The application is looking for a Quickr Node Type on Since Quickr Node Types are not guaranteed to be installed on a base WebSphere Portal installation, this error calls for an update for the application. In this customer-reported case, the issue was found with PZN and the issue is resolved with PK51123.

Error deleting a library: SQL0101N

The SQL0101N error indicates that the SQL is too large or complex. One needs to ensure that the database statistics are current, especially if running DB2. Depending on the nature of your environment's data set, specific database tuning may be required to resolve this error. In the case of using DB2, the presence of the large number of versions is creating a SQL statement that exceeds the settings for DB2 cache size.


* Increase the DB2 parameter: pckcachesz. This parameter is allocated out of the database shared memory, and is used for caching of sections for static and dynamic SQL and XQuery statements on a database. Try using 16382 for value.
NOTE: The database manager must be restarted for these updates to take effect.
* Verify the new value is set before retrying. If it fails again, then double the value specified in the previous step.
NOTE: the value can be reduced once the library is removed.


For complete details about OutOfMemoryError during export, read JCR Troubleshooting topic: Export and Import, technote 1322146.

JCR Troubleshooting topics: Export and Import
There are often cases where the OutOfMemoryError is caused by the application processing too much data when using a StrongWorkspaceState. You can recognize this situation when you see the StrongWorkspaceState holding a lot of memory when you analyze the heap dumps. The StrongWorkspaceState is an internal cache of all JCR nodes referenced in the current workspace, and the OutOfMemoryError here indicates that more nodes are referenced than the current memory can handle.

The application needs to change to do one of the following:

1. Reduce the number of nodes processed per workspace
2. Manually clear the workspace state at an interval that can be handled by the system's memory
3. Use Weak workspace state

Applying PK70951 will not resolve the problem alone, but it will help identify what part of the application that is improperly using the StrongWorkspaceState.

After applying PK70951:

1. Enable trace to, and
2. Recreate the failure.

After the next OutOfMemoryError, the trace will contain debug stack traces which can be used by IBM Support to identify the failure. Otherwise, this error needs more diagnostic information to determine the cause, including Java core output and the heap dump of the failure.


The StaleValueException is a normal exception by JCR and does not indicate a JCR failure. JCR throws StaleValueException when the current node being saved is different from the latest version of that node in the database.

There is a known issue with JCR nodes which have been created or updated within the first hour after the time switch to Daylight Savings Time (DST). The cause of this problem is that Java compensates for DST differently than the database. During this hour of overlap, Java advances internal timestamps one hour ahead. The database does not advance the timestamp during this time period, so the result is an inconsistency between timestamps from Java and database timestamps. The end result is that the user encounters a StaleValueException every time they try to update nodes from this hour of overlap.
IBM support has a utility to fixup the invalid nodes during this hour of overlap. Contact IBM Support to review the issue and provide the utility if indicated.


javax.jcr.query.InvalidQueryException: Query exception is thrown for query statement: /contentRoot/element(*,icm:documentLibrary)/Taxonomies/mig/My Taxonomy/My Organization/North Carolina: QRY0552E: Syntax of query string is incorrect. Parsing error at position 71. Detail: Error: could not match input.

The application needs to correctly encode the query before sending it to JCR.


This message is not necessarily an error. It indicates that the caller is looking for a JCR object that does not exist. You need to look up the call stack to the calling application to determine where to debug further.


This message is not necessarily an error. javax.jcr.ItemExistsException indicates that the caller is trying to save a JCR object that already exists. The object may already exist by either the same path or the same UUID.
We have also seen ItemExistsException occur during import. For more information, read JCR Troubleshooting topic: Export and Import, technote 1322146.

Data field is too long

Example: javax.jcr.nodetype.ConstraintViolationException: The value for the string property ibmcontentwcm:writeAccess on node /contentRoot/icm:libraries[5]\/Workflow/Stages/test/ibmcontentwcm:effective exceeds its max length.

The maximum length is 252 while the value is of length 263
This message indicates that the application is sending a data property value which is greater than its definition size. This is most commonly seen when migrating WCM data from 5.1 to V6. If this problem is occurring during WCM migration, this error indicates that a 5.1 property needs to be shortened in order to fit into the V6 size restrictions.

If this problem is not occurring during WCM migration, implement application debugging to proceed further.

SQLSTATE=54001 - The statement is too long or too complex.

This error can occur if you have not regularly executed database statistics. Ensure that the database statistics are current.

For more information, read the IBM WebSphere Portal Information Center topic: Database performance.

If using DB2 as the database:

1. Increase the values of the DB2 statement heap (stmtheap), the application heap (applheapsz) and the cache size (pckcachesz).
2. Restart the database manager for these updates to take effect.

NOTE: If this failure occurs during a one-time operation such as library delete, you can reduce these values after delete has completed. Bad file number

Example: Bad file number
at Method)

This exception is reported because the data stream being stored inside JCR is invalid.

getMimeTypeId errors

Example: java.lang.NullPointerException at

This error is encountered when the MimeType extensions had been manually edited. Make sure that has the correct extension mappings.

Problems in LibraryDeleteModule

Older versions of LibraryDeleteModule would cause database exceptions when deleting drafts (internal locks). This has been resolved by PK64844. Ensure that your system has the latest version of the LibraryDeleteModule.

Fail to create database

The prefix must be unique enough to contain only the databases used for the content repository. Use a prefix that provides unique database name conventions, such as DPTJCRXXX, or something similar.


Error with ordered results

There is a known defect with ordering on Oracle The result is that an ordered list from JCR may not be returned in the correct order. IBM recommends upgrading to Oracle or higher to resolve this problem. For more information, read "Menu ordering is broken in Web Content Management (WCM) due to bug in Oracle" technote 1266428.

Sort issues may also indicate a query problem. To troubleshoot SQL queries:

1. Collect the database response
2. Look to the output from the repository class that identifies the SQL statement that will be issued against the database.
3. Once this SQL statement is identified, manually execute the query against the database to see if the results are ordered correctly and as expected. If the results do not appear in the expected order, open a support ticket with the database vendor support team.

Portal 6.0
DB2 engine SQL error, SQLCODE = -104, SQLSTATE = 42601, error tokens = ,1;+ - AS

There is a problem on a German locale where the comma character is allowed as a period. Ensure that you have the latest JCR cumulative fix to resolve the problem.