The Ultimate XConnect Troubleshooting Guide

Many of us have been there: whether it’s a matter of containerizing an existing solution, moving an instance to a different machine, or even just setting up our local development environment, many Sitecore developers had to square off with a non-functional XConnect instance.

Last week was the third time in my career, so I decided to make a little experiment: I configured an instance completely from scratch in a VM that never had Sitecore running on it, and documented all the steps that led from an empty wwwroot folder to a working XConnect site.

For reference, I’m installing XConnect version 10.1.0, on a Windows 10 server running IIS 10; additionally, I assume that Sitecore software prerequisites have already been set up.

  • First and foremost, ensure that your Databases, Solr instance and TLS/SSL Certificates are in place. I will not go into the details of setting up  SQL Server or a SOLR instance, but if you need to set up your security certificates from scratch you can use this Powershell script. Doing so will create 4 certificates in your machine’s Personal store; of those, the Sitecore Development Root certificate must be copied in the Trusted Root Certification Authorities store.
  • Whatever TLS/SSL certificate you’re going to use, ensure that the LOCAL SERVICE, XConnect Application Pool, CM / CD Application Pools and Identity Server Application Pool users have access to it; you can do so by right-clicking the XConnect certificate in the Personal store, selecting “All Tasks” and “Manage Private Keys”:

                                 

  • Configure your XConnect site to Accept Client Certificates:

  • Also, be sure to note down the Thumbprint of your XConnect certificate by double-clicking on it in the Personal store and selecting Details:

  • Having done this, update all the instances of ConnectionStrings.config and AppSettings.config with the correct SQL Server Connection Strings, SOLR server URL and XConnect Certificate Thumbprint;
  • If your local SOLR service is not HTTPS, you may have to search throughout the .xml files in the XConnect folder for all the <RequireHttps>….</RequireHttps> entries and change it to “false”;
  • Ensure that the proper users (typically IIS_IUSRS, NETWORK SERVICE and/or the IIS App Pool user) all have access to the IIS folder where XConnect is running from;
  • If your IIS version has this option, ensure that in the HTTPS bindings for the XConnect website, “Disable TLS 1.3 over TCP” is checked:

  • Create the three separate Windows Services associated to XConnect; put the .exe path between brackets, and add the string “-service” at the end of it, for example:

“C:\inetpub\wwwroot\sc101sc.xconnect\App_Data\jobs\continuous\AutomationEngine\Sitecore.MAEngine.exe” “-service”
“C:\inetpub\wwwroot\sc101sc.xconnect\App_Data\jobs\continuous\ProcessingEngine\Sitecore.ProcessingEngine.exe” “-service”
“C:\inetpub\wwwroot\sc101sc.xconnect\App_Data\jobs\continuous\IndexWorker\Sitecore.XConnectSearchIndexer.exe” “-service”

and use the NT AUTHORITY\LocalService user as Logon Account; then start them.

  • Finally, ensure that a valid Sitecore License is present in the App_Data folder of each of those services.

This should result in a working XConnect instance; if for some reason it doesn’t, please feel free to let me know.

Leave Comment