Wednesday, July 30, 2014

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


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.

  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.
  • 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".


Anonymous said...

when Get-Cachehost I get 3 Hostnames - one I would like to remove... following the guide you provided - but then I see this

Unregister-CacheHost : ErrorCode:SubStatus:No such host is known
At line:1 char:1
+ Unregister-CacheHost -HostName "Servertoremove:port"
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Unregister-AFCacheHost], DataCacheException
+ FullyQualifiedErrorId : UnspecifiedErrorCode,Microsoft.ApplicationServer.Caching.Configuration.Commands.UnregisterAFCacheHostC

can you plz advise?

Al said...

Don't use port number and don't quotation marks for UnRegister-CacheHost

Jeff C. said...

Hi Al, I was hoping you could help me with what I have going on. I have a server that is dead and gone but showing up in my Get-CacheHost as an Unknown. I've tried to unregister it but have had no luck. Any advice? thanks in advance :

PS C:\> Get-CacheHost

HostName : CachePort Service Name Service Status Version Info
-------------------- ------------ -------------- ------------
GOIO-SPSQL01.go.local:22233 AppFabricCachingService UP 3 [3,3][1,3]
GOIO-SPWEB01.go.local:22233 AppFabricCachingService UNKNOWN 0 [0,0][0,0]
GOIO-SPWEB02.go.local:22233 AppFabricCachingService DOWN 3 [3,3][1,3]

PS C:\> Unregister-CacheHost -HostName goio-spweb01.go.local

cmdlet Unregister-AFCacheHost at command pipeline position 1
Supply values for the following parameters:
ProviderType: SPDistributedCacheClusterProvider
ConnectionString: Data Source=goio-spsql01.go.local;Initial Catalog=SharePoint_C
onfig;Integrated Security=True
Unregister-CacheHost : ErrorCode:SubStatus:No
such host is known
At line:1 char:1
+ Unregister-CacheHost -HostName goio-spweb01.go.local
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : NotSpecified: (:) [Unregister-AFCacheHost], Data
+ FullyQualifiedErrorId : UnspecifiedErrorCode,Microsoft.ApplicationServer
PS C:\>

Al said...

Jeff - first off, if I read things correctly from what you pasted above, you're running AppFabric on one of your SQL Server backends. I would recommend removing it from this. The reason being that AppFabric can consume lots of memory and this will directly impact SQL Server performance. Second, my experience has been that merely unregistering AppFabric from a server hasn't been enough: I've also had to remove it. Please see This Distributed Cache host may cause cache reliability problems (SharePoint 2013). Then review SharePoint 2013: This Distributed Cache host may cause cache reliability problems, which provides steps for deleting and removing the service.