Troubleshooting “Velocity” Series



Hope all of you are having great time caching your data with Microsoft project code named “Velocity”. This post is first in the series of some practices and guidelines to follow in order to make best use of “Velocity” and for troubleshooting any common issues you may face. I also recommend that you see the “Velocity” readme file and the product help file for other known issues. You can find the code_name_velocity_readme.txt file on the “Velocity” download page.

How to work with common “Velocity” exceptions

The occurrence of any undesired behavior in “Velocity” cache requests results in DataCacheException being thrown to the client application. So the application using “Velocity” should be capable of catching them, recovering and taking appropriate actions, for instance, retrying a retry-able error or falling back to the persistent data store.

A “Velocity” client application should check for the exception’s ErrorCode field. These are explained in the documentation in detail. There are error codes like DataCacheErrorCode.KeyDoesNotExist, DataCacheErrorCode.RegionDoesNotExist, etc. which point to logical issues and represent definite failures. However, there also exist some error codes which may come due to cluster’s temporal state of re-alignment as a result of a cache host coming up, going down, named cache getting created/deleted etc. These are explained here and should be taken care of.

1.       DataCacheErrorCode.RetryLater : this error code represents transient incapability of the cluster to serve a request. Application can retry the request.

For instance, this would be thrown when the cluster is undergoing a configuration change or there are not enough cache hosts in the cluster to perform a Put/Add.

In the next release, this error code would be accompanied by an error sub-status which would tell the exact reason for this failure. For example – primary cache copy not found, secondary cache copy not found to update, etc to name a few.

2.       DataCacheErrorCode.Timeout : this error code is thrown when the client doesn’t receive a response from the server within a specified timeout. For instance, this would be thrown when there is a glitch in underlying communication between client and the server.

However, there is a possibility that the request may have been processed by the server, so application logic should take care of that while retrying.

To clarify a bit more, suppose client does


 cache.CreateRegion(“Foo”, false);


and gets a Timeout error code. Trying again may result in an exception with code DataCacheErrorCode.RegionAlreadyExists.


If the deployment mode is chosen as ‘Simple’, there is one more error code which the application should take care of – DataCacheErrorCode.CacheServerUnavailable. This is thrown when a “Velocity” client is not able to reach a particular cache host. This may be possible if that server is down or there is some network related failure.


Next in the series is ‘How to ensure you have correct client libraries’.


Amit Kumar Yadav

(Microsoft project code named “Velocity” team)

Comments (1)

  1. MichaelGG says:

    Why not throw different exceptions subclassed from a root velocity exception?