Here are some pointers to troubleshoot JBossCache (TreeCache).

Q. What is the version number of JBoss Cache ?

Use: java -jar jboss-cache.jar

Q. What is the log4j trace category ?

The log4j trace category is org.jboss.cache. There are couple of different sub-categories that can be fine tuned.

Q. Replication does not seem to be working, how do I check ?

• First of all, make sure mcast is working in your environment. You can check the JGroups troubleshooting page for this.

• Try to run the tutorial first on the GUI demo. They should work first.

• Try to run the tests that bundled in the distribution. They should have run successfully.

• If you have gone through the aboe steps, then next step is to check the log to see why it is not replicated. Look for the _replicate keyword in the log. JBoss Cache uses replicate method call to perform replication.

• Next step is to check if there is other expcetion output the log. For example, if you run it under transaction, has it been rolled back?

Q. I have set up an eviction region but none of the nodes in that region get evicted.

Make sure that the region starts with the / character, i.e.

<region name="/org/jboss/data" ...

Q. I get "org.jboss.cache.CacheException: Initial state transfer failed: Channel.getState() returned false"

See debugging state transfer wiki.

Q. I have set up the InitialStateRetrievalTimeout, but there's no state transfer happening on startup

Make sure that the state transfer protocol has been set up in the JGroups configuration stored inside JBoss Cache configuration:

<pbcast.STATE_TRANSFER up_thread="true" down_thread="true"></pbcast> 

Q. I'm using JDBCCacheLoader with JBoss Cache and data is written correctlty to the database, but when JBoss Cache stops, the table is deleted, how can I avoid that ?

Set cache.jdbc.table.drop to false in the CacheLoaderConfig (prio version 2.1 the default value is true):

    <attribute name="CacheLoaderConfig" replace="false">
      cache.jdbc.datasource=java:/DefaultDS
      cache.jdbc.node.type=bytea
      cache.jdbc.table.drop=false
    </attribute> 

Q. In JBoss Cache 1.3.x, I get "java.lang.IllegalArgumentException: TreeCacheMarshaller.extractFqn(): Unknow method call name: optimisticPrepare"

Optimistic locking and UseMarshalling cannot be used at the same time as explained in JBCACHE-634

Alternatively, either set UseMarshalling to false or use Pessimistic Locking.

Q. I'm using JBoss Cache 1.3.0 (or 1.3.0.SP1) and I keep getting org.jboss.cache.lock.TimeoutException exceptions under high load

Upgrade to 1.3.0.SP2 as it fixed some issues around transaction handling.

Q. I want to upgrade to JBoss Cache 1.4.0 (or later) from 1.3.0 (or before), for example in JBossAS 4.0.3.SP1.  What jars to I need?

In most cases, upgrading JBoss Cache just involves updating the jboss-cache.jar library.  When upgrading to JBoss Cache 1.4.0 or later from 1.3.0 or before, however, you also need to make sure the jboss-serialization.jar library that ships with JBoss Cache is made available.

It is also recommended (but not required) that you upgrade to the latest version of JGroups, for improved performance and reliability.

Q. I'm using org.jboss.cache.GenericTransactionManagerLookup as the TransactionManagerLookupClass and jboss:service=TransactionManager service fails to start due to a javax.naming.NameAlreadyBoundException being thrown, what is happening?

Setting org.jboss.cache.GenericTransactionManagerLookup as the TransactionManagerLookupClass allows JBoss Cache to look for the transaction manager in a application server independent way by looking for the common transaction manager definitions in JBoss, BEA, Wepshere,...etc. However, if you don't set the dependency on a specific transaction manager service, it can lead to this exception.

If JBoss Cache starts before the transaction manager does, the transaction manager lookup will fail falling back on the DummyTransactionManager, and binding it in the JNDI. When the actual TransactionManager starts, it will fail binding it because the DummyTransactionManager occupies it.