SharePoint 2013: how to remove a cache host from an unrecoverable farm server

Introduction

This posting walks through the steps necessary for removing a distributed cache host from a SharePoint farm server that has been removed, terminated, or is otherwise unrecoverable.

Procedure

1. Preparation
1. Identify the name of the unrecoverable cache host (eg, SERVER1).
2. Identify the connection string used by the distributed cache service to connect to the farm database:
1. On any farm server hosting SharePoint, launch a command prompt with elevated privileges.
2. Execute regedit.
3. Navigate to: HKLM\SOFTWARE\Microsoft\AppFabric\V1.0\Configuration.
4. Open a new NotePad instance.
5. Copy the contents of the ConnectionString parameter to NotePad.
6. Remove the last parameter of this string, or ";Enlist=False" including the ";".
7. Save this text; you'll need it later.
2. Connect
1. Login to a SharePoint farm server as the SharePoint Setup User Administrator account.
2. Launch the SharePoint 2013 Management Shell with elevated privileges.
3. Check cache status
1. Execute Use-CacheCluster and then Get-CacheHost to check current distributed cache status.
4. Unregister the cache host:
1. Execute Unregister-CacheHost -HostName "YourHostName"
2. At the prompt for ProviderType, enter SPDistributedCacheClusterProvider.
3. At the prompt for ConnectionString, enter the string you saved back in Preparation step 1.7.  Unregistration takes only a few seconds.
5. Check cache status
1. Execute Get-CacheHost to check current distributed cache status.  The target cache host should no longer be listed.
2. Execute Stop-CacheCluster followed by Start-CacheCluster: these commands should complete without any errors and without the target cache host being listed.

References

• Manage the Distributed Cache service in SharePoint Server 2013
• Delete Cache Host, SharePoint 2013
• AppFabric Caching PowerShell Cmdlets: this is the complete reference for all PowerShell commands used for AppFabric.
• Use-CacheCluster
• Get-CacheHost
• Unregister-CacheHost
• Stop-CacheCluster
• Start-CacheCluster
• Sample: RemoveCacheHost Script (Windows Server Appfabric Caching)
• Windows Server AppFabric Caching Deployment and Management Guide: this was written for SharePoint 2010, but is still an outstanding reference.  This link takes you to the downloadable document.
• AppFabric 1.1 Caching Deployment and Management Guide

Notes

• Stop-CacheCluster: There's no need to bring down the cache cluster before unregistering the target cache host.  if you do first bring it down, and then try to execute the Unregister-CacheHost command, you may experience an error:

  Unregister-CacheHost : ErrorCode<ClusterNotInitialized>: SubStatus<ES0001>:No cluster configuration is present in target.

  .
• Unregister-CacheHost: Don't use the Unregister-CacheHost format presented in the Windows Server AppFabric Caching Deployment and Management Guide, page 13.  This won't work.  Instead, use the steps I've provided in the Unregister the cache host section, above.
• Servers in Farm: you may need to remove the target server from the farm.
• ConnectionString: you can also use PowerShell to get this value.  To do so: open a SharePoint management shell with elevated privileges.  Then execute the following:

  Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\AppFabric\V1.0\Configuration"

  Note that you are using "HKLM" and not "HKEY_LOCAL_MACHINE".