Every Sitecore Instance using GQL is prone to this scenario of template not found - Sitecore Component With GQL Queries Broke On Production

Hello Team,

Today, I wanted to share a real scenario and a solution of it about what happened  suddenly to our components and how we identified it and how we resolved it, and most importantly it could happen to your installations too

Scenario

We have one Sitecore 10.2 headless instance and two sites, One site is non-sxa which is legacy site and another site is a new site which uses headless SXA.

Now, non-sxa site is already live and working fine with all components etc. and the new headless site was in development and it has separate development team, So we have same DEV/UAT/PROD environments.

One fine morning they took their code and site on environment but strangely some of the GQL components like header footer of legacy site disappeared. 

Troubleshooting Steps

1) We checked the broken component's GQL query 

2) We took that query and fired it in GQL IDE, and we observed that, Some of the templates references we used were not found, which was working just fine and we have not had any deployment of this site, see below what it was giving 

3) Now, one thing was clear, that the path of this "Link" template the tooltip is showing is not the one we referenced in our query, if you see the tool tip on above screenshot it is showing the path of SXA template which does not have those fields, Our legacy site does not use SXA.

4) Upon further investigation, we found out that, the other team who is sharing Sitecore instance have installed headless-sxa package and it seemed like it somehow now taking that template

5) We double checked and our custom "Link" template which was on another path was also there but it was somehow giving precedence to this SXA template.

6) We knew how GQL schema is generated, If there are templates with the same name exists in the tree, then precedence will be given to the one which has older date and the template which is of later date will be renamed with _GUID format, Read on link

Sitecore GQL Schema 

If you read the paragraph highlighted below from the Sitecore link

7) We were still puzzled because our custom "Link" template was older as we are live from long time and the headless-sxa package was just recently added, so that should have newer date, So we went on to check the date of that template which was generated by installing the package.

8) With our surprise, it has very old date for obvious reasons, because the package is standard package and it comes up with its own date when package was created by Sitecore. See below

We knew the issue now, but what is the solution? Because headless-sxa package is now overriding the behavior because it is having the older dates in its template.

Solution

1) Change your queries to have template name with _GUID, Because that is the correct template, but in this case you will need to change all the places where this template is used.

2) You can modify the <AddIncludePaths> configuration in the GraphQL schema custom configuration, so that you can exclude the SXA path in generating template schema and configure only those templates which you are using in GraphQ like below.

Default Configuration

By default Sitecore uses helix schema and edgeschema to target specific template path depending on helixContentSchema and edgeSchema configuration like below, and if you observer it will create template schemas for all those given on below paths, now all SXA related folders are also inside these folders only, so it also creates schema for those too. 

Now, if you have a different folder or a path which you want to target, You can patch your custom graph GQL schema configurations so it targets only specific path and generates template schemas for those path only like below 

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:role="http://www.sitecore.net/xmlconfig/role/">
	<sitecore>
		<api>
			<GraphQL>
				<endpoints>
					<customGraphQLEndpoint>
						<schema>
							<content>
								<templates>
									<paths>
										<patch:delete />
									</paths>
									<paths hint="list:AddIncludedPath">
										<feature>/sitecore/templates/Feature/Content/MyCustomPath</feature>
									</paths>
								</templates>
							</content>
						</schema>
					</customGraphQLEndpoint>
				</endpoints>
			</GraphQL>
		</api>
	</sitecore>
</configuration>

But the limitation here is, We have "AddIncludedPath" tag but we do not have "AddExcludedPath" tag, so if you have so many path to include but if you have only one path you want to exclude, It is not possible right now, instead you will need to have all those custom path registered in "AddIncludePath" for which i raised the feature request and Sitecore has acknowledge it and taken as feature request with reference no. DEVEX-2997

I hope this scenario will save troubleshooting time for you all, Because this could easily exist in your set up too.