Common Exceptions (Windows Server AppFabric Caching)

When an error occurs during a cache client method call, the cache client throws an instance of the DataCacheException class. The ErrorCode property contains the type of error.

Each cache client API has the potential to experience one of several common errors:

Your application code should be designed to anticipate these errors. The following information provides additional details on each error that should help you to appropriately handle each situation.


When a timeout occurs, a DataCacheException object is thrown with an error code of Timeout. A timeout indicates that the cache client did not get a response from the server within the configured timeout settings. This could be caused by a variety of problems, such as network issues between the client and server.

Even though the timeout error occurs, it is important to note that the server may have successfully processed the requested operation. For example, consider an application that has a cache client with a requestTimeout set to 10000 milliseconds. The application makes a call to the Add API to add a new cache item. If the call takes longer than ten seconds, the application receives a timeout error. However, the server could have completed the add operation, and then it was unable to respond to the client before the timeout elapsed. In the error handler, the application should consider this possibility. If the error handler simply attempts to add the object again, it could result in another exception with the error code of KeyAlreadyExists.

Depending on application design requirements, you can lengthen or shorten the duration of cache client timeouts. For more information about how to configure the timeout duration, see Configuring Cache Client Timeouts (Windows Server AppFabric Caching).


The RetryLater error code indicates that the cache cluster is temporarily unable to complete a request. For example, this error could be experienced if an administrator is configuring the cache cluster.

With this type of error, it is important to observe the value of the SubStatus property of the DataCacheException object. This property provides additional details that explain the reason for the failure. For example, if the cache cluster is stopped, the thrown DataCacheException will have the ErrorCode property set to RetryLater and the SubStatus property set to CacheServerUnavailable. Note that this same SubStatus value would be seen if the Windows Account associated with the request was not allowed on the cache cluster or if the firewall on the cache hosts were not properly configured.

The RetryLater error code can also occur when one or more of the target servers are low on available memory. In this situation, the SubStatus property is set to Throttled. There are several factors that can contribute to a throttled cache server.

  • Check the cache settings with the get-cacheconfig Windows Powershell command. Look for caches that have EvictionType set to None instead of LRU. If eviction is disabled, then the cache cluster is unable to evict cached items when the server is low on memory.

  • Use Windows Task Manager or the Performance Monitor to look for other processes on the cache servers that might be using the available memory.

  • Examine the application's use of the cache. The average rate of objects inserted, their size, and their timeout values all contribute to the total amount of memory needed on the cache cluster.

  • Consider the use of custom regions. A region resides on only one cache server, so the items in a region cannot be spread across all of the cache hosts. If one or more large regions reside on a single cache server, then that server could be in a throttled state even if the other cache servers have available memory.


The ConnectionTerminated error code indicates that the connection between the cache client and the cache cluster was aborted. There are a variety of possible causes for this error, including network errors or shutting down the cache servers. As with timeout errors, the ConnectionTerminated error does not reflect the success or failure of the requested operation. The error handler should anticipate both possibilities.

See Also

Community Additions