The reason to get the GraphQL simple fragment matcher error is that you use interface types (e.g ‘… on MediaImage’) in your GraphQL queries. It occurs when you have two or more subtypes in your response (e.g MediaImage and Video that both inherit Media). To fix this you need to use IntrospectionFragmentMatcher. This requires you to import the whole Shopify GraphQl schema (type definitions).

For SEO purposes I provide the full text of the error: ”You are using the simple (heuristic) fragment matcher, but your queries contain union or interface types. Apollo Client will not be able to accurately map fragments. To make this error go away, use the `IntrospectionFragmentMatcher` as described in the docs: https://www.apollographql.com/docs/react/advanced/fragments.html#fragment-matcher”

The hard part for me was to get all the pieces together. However, finding out how to generate the Shopify GraphQL schema was not an easy task as well.

Why I got the GraphQL simple fragment matcher error in my Shopify Embedded App

I’m the author of PicAmaze – Shopify embedded app to add animations to product images. We use the GraphQL to get the media images attached to a product. For example the following query can do that:


Copy to Clipboard

As you can see the query contains ‘… on MediaImage‘. This means: if the media of the product is an image, then populate those fields. The error occurs when you put a video in the product you try to execute the query above.

How to fix the fix GraphQL simple fragment matcher error

Here are the steps:

  1. Firstly generate the schema with graphql-codegen cli in JS format 
  2. After that import it in your _app.js, construct the IntrospectionFragmentMatcher with it
  3. Then pass the schema to the AppProvider

Generate the Shopify Admin API GraphQL schema

Install @graphql-codegen/cli and @graphql-codegen/fragment-matcher packages

Copy to Clipboard
Full instructions here.

Create gqlcodegen.yml

Firstly, create the file in your project. Secondly paste the following in it:

Copy to Clipboard

Generate the schema

Firstly, execute the following commands

Copy to Clipboard

However, I put the command to generate the schema in my package.json file. This way I can easily update it on the production environment. 

Import the Shopify Admin API GraphQL schema in your app

Edit your _app.js file as follows:

Copy to Clipboard

It took me a while to gather all the pieces. However, now the app works just fine. I want to save other people’s time putting it all together. I’ve used such copy/paste solutions so many times in my development experience. Therefore, I want to give back.

Happy coding!

P.S If you want to speed up the development of your Shopify Embedded app, make sure you run and view it on localhost. Here is how to do this – read my previous article.