Checks reference

You can run the following checks as part of Theme Check. Each check identifies a specific error or a place in your code where a best practice is not being followed.

Checks are grouped by category to help you to understand their purpose. Some checks are in multiple categories.

To learn more about the check and its options, click on the name of the check.

Including or excluding check categories

Anchor link to section titled "Including or excluding check categories"

You can include or exclude certain categories of checks using the --category <CATEGORY> or --exclude-category <CATEGORY> flag. This flag accepts the following values:

html
json
liquid
performance
translation

For example, to run only Liquid checks for a theme, use the command shopify theme check --category liquid. To disable translation checks, use the command shopify theme check --exclude-category translation.

You can specify multiple categories using multiple instances of the flag:

HTML checks

Anchor link to section titled "HTML checks"

These checks analyze the content of HTML files.

Check	Severity	Purpose
AssetPreload	Suggestion	Encourages preloading of assets using Liquid filters, rather than HTML attributes.
AssetSizeCSS	Error	Prevents themes from using CSS files larger than the configured threshold.
AssetSizeJavaScript	Error	Prevents using theme JavaScript files and external scripts with a compressed size greater than the configured threshold.
DeprecateBgsizes	Suggestion	Discourages use of the bgset extension instead of the image-set attribute for loading background images.
DeprecateLazysizes	Suggestion	Discourages use of the lazysizes library for lazy loading images, iframes, and scripts.
HtmlParsingError	Error	Reports errors preventing the HTML from being parsed and analyzed by Theme Check.
ImgLazyLoading	Suggestion	Suggests lazy loading for images to increase performance.
ImgWidthAndHeight	Error	Enforces setting the `width` and `height` attributes on `img` tags.
ParserBlockingJavaScript	Error	Identifies script tags that don't have defer or async attributes, avoiding parser-blocking JavaScript.
RemoteAsset	Suggestion	Discourages the use of third party domains for hosting assets.

JSON checks

Anchor link to section titled "JSON checks"

These checks analyze the content and structure of JSON files and syntax.

Check	Severity	Purpose
ValidJson	Error	Identifies invalid JSON files in themes.
ValidSchema	Suggestion	Identifies invalid JSON in `{% schema %}` tags.
ValidHTMLTranslation	Suggestion	Identifies invalid HTML inside translations.

Liquid checks

Anchor link to section titled "Liquid checks"

These checks analyze the style and validity of Liquid code. Some of these checks support auto-correction using the --auto-correct flag.

Check	Severity	Purpose	Auto-correction
AppBlockValidTags	Error	Identifies forbidden Liquid tags in theme app extension app block and app embed block code.
AssetSizeCSSStyleSheetTag	Error	Prevents themes from referencing CSS files larger than the configured threshold using a Liquid stylesheet tag.
AssetUrlFilters	Error	Encourages the use of `asset_url` or `img_url` filters to serve assets.
ContentForHeaderModification	Error	Identifies code that tries to parse `content_for_header`.
ConvertIncludeToRender	Suggestion	Discourages using the deprecated `include` tag instead of the `render` tag.
DeprecatedFilter	Suggestion	Discourages using deprecated filters in themes.	Yes (`img_url` only)
DeprecatedGlobalAppBlockType	Error	Makes sure that theme sections are not using the deprecated `@global` block type to support or render app blocks in a section.
LiquidTag	Suggestion	Recommends using {% liquid ... %} if four or more consecutive Liquid tags (`{% ... %}`) are found.
MissingEnableComment	Error	Makes sure that when `theme-check-disable` is used in the middle of a template, the corresponding `theme-check-enable` comment is also present.
MissingRequiredTemplateFiles	Error	Makes sure that all template files required for the Shopify Theme Store are present.	Yes
MissingTemplate	Suggestion	Identifies when a resource is referenced using a `render`, `section`, or `include` tag, but doesn't exist.	Yes
NestedSnippet	Suggestion	Reports deeply nested `render` tags or `include` tags.
ParserBlockingScriptTag	Error	Identifies the use of the `script_tag` filter.
RequiredDirectories	Error	Makes sure that all template files required for the Shopify Theme Store are present.	Yes
RequiredLayoutThemeObject	Error	Makes sure that the theme.liquid layout file contains the required `{{ content_for_header }}` and `{{ content_for_layout }}` objects.	Yes
SchemaJsonFormat	Style	Identifies improperly formatted JSON in `{% schema %}` tags.	Yes
SpaceInsideBraces	Style	Identifies inconsistent spacing inside Liquid tags and variables.	Yes
SyntaxError	Error	Identifies Liquid syntax errors.
TemplateLength	Suggestion	Identifies large Liquid template files.
UndefinedObject	Error	Identifies references to undefined Liquid objects.
UnknownFilter	Error	Identifies references to unknown Liquid filters.
UnusedAssign	Suggestion	Identifies variable definitions that aren't used.	Yes
UnusedSnippet	Suggestion	Identifies snippets that aren't used.	Yes

Performance checks

Anchor link to section titled "Performance checks"

These checks look for common performance issues in theme code.

Check	Severity	Purpose
AssetPreload	Suggestion	Encourages preloading of assets using Liquid filters, rather than HTML attributes.
AssetSizeAppBlockCSS	Error	Prevents theme app extensions from using CSS files larger than the configured threshold.
AssetSizeAppBlockJavascript	Error	Prevents theme app extensions from using JavaScript files and external scripts with a compressed size larger than the configured threshold.
AssetSizeCSS	Error	Prevents themes from using CSS files larger than the configured threshold.
AssetSizeCSSStyleSheetTag	Error	Prevents themes from referencing CSS files larger than the configured threshold using a Liquid stylesheet tag.
AssetSizeJavaScript	Error	Prevents using theme JavaScript files and external scripts with a compressed size greater than the configured threshold.
AssetUrlFilters	Error	Encourages the use of `asset_url` or `img_url` filters to serve assets.
DeprecateBgsizes	Suggestion	Discourages use of the bgset extension instead of the image-set attribute for loading background images.
DeprecateLazysizes	Suggestion	Discourages use of the lazysizes library for lazy loading images, iframes, and scripts.
ImgLazyLoading	Suggestion	Suggests lazy loading for images to increase performance.
ImgWidthAndHeight	Error	Enforces setting the `width` and `height` attributes on `img` tags.
PaginationSize	Suggestion	Ensures that objects are paginated with performant sizes so too many objects are not loaded at once.
ParserBlockingJavaScript	Error	Identifies script tags that don't have `defer` or `async` attributes.
ParserBlockingScriptTag	Error	Identifies the use of the `script_tag` filter that isn't wrapped in a script tag with `defer` or `async` attributes.
RemoteAsset	Suggestion	Discourages use of third party domains for hosting assets.

Translation checks

Anchor link to section titled "Translation checks"

These checks ensure that translations are complete. Some of these checks support auto-correction using the --auto-correct flag.

Check	Severity	Purpose	Auto-correction
DefaultLocale	Suggestion	Makes sure that the theme has a default locale file.	Yes
MatchingSchemaTranslations	Suggestion	Identifies missing or additional translations in `{% schema %}` tags.	Yes
MatchingTranslations	Suggestion	Identifies missing or additional translations in locale files.	Yes
TranslationKeyExists	Error	Identifies references to translations that don't exist.	Yes