Running shopify theme check --output json --fail-level error gives you a machine-readable audit of every Liquid and JSON problem in your theme, and exits with code 1 the moment any error-severity issue is found. That exit code is what makes it useful as a hard gate in GitHub Actions, GitLab CI, or any pipeline: a broken build stops a bad deploy. What most guides skip is what to do with the JSON output itself, and why the errors it surfaces also hurt your AI search visibility, not just your store's code quality.
Key Takeaways
--fail-level error(the default) exits with code1on any error-severity finding;--fail-level suggestionis stricter and catches more issues.--output jsonemits a structured array of offenses withpath,severity,check,message,start_row, andstart_columnfields you can pipe into scripts or dashboards.- JSON errors in
{% schema %}blocks andsettings_schema.jsonare also structured-data errors: they corrupt the Product JSON-LD your theme auto-emits. - Shopify CLI 4.0 (released May 2026) requires Node 22.12+ and Git 2.28+ and self-upgrades via your package manager by default, but skips auto-upgrade inside CI environments.
- Fixing theme check errors is step one; auditing the rendered JSON-LD those templates produce is a separate, equally important step for AI search visibility.
What the Command Actually Does
shopify theme check is a linter for the Liquid and JSON inside your theme and theme app extensions. It detects errors and enforces Liquid best practices, and every error includes a link to the failed check's documentation so you can debug issues quickly.
The two flags you care about most:
| Flag | What it controls | Default |
|---|---|---|
--fail-level error | Exit code 1 when any error-severity finding exists | error (this is already the default) |
--fail-level suggestion | Exit code 1 on suggestions, warnings, and errors | Not the default; stricter |
--fail-level warning | Exit code 1 on warnings and errors | Not the default; middle ground |
--output json | Emits findings as a JSON array instead of human-readable text | Human text |
--auto-correct | Fixes auto-correctable issues in place (e.g. prettifies {% schema %} JSON) | Off |
Putting them together:
shopify theme check --output json --fail-level error . > theme-check-results.jsonThis writes every finding to theme-check-results.json and exits with code 1 if any error is present, which is exactly the signal your CI system needs to block a merge or deploy.
Since CLI 4.0 (May 2026), the tool self-upgrades through your package manager by default but skips upgrading inside CI, and it now requires Node 22.12+ and Git 2.28+. If your pipeline runner is on an older Node version, the command will fail before it even scans a file.
How to Read the JSON Output
Each item in the output array represents one offense and contains:
path- the file where the issue was found (e.g.sections/main-product.liquid)check- the check name (e.g.ValidJSON,MissingRequiredTemplateFiles,JSONSyntaxError)severity-0for error,1for warning,2for suggestion (string and integer forms are equivalent)message- a human-readable descriptionstart_row/start_column- exact location in the file
A minimal parse in a shell pipeline:
cat theme-check-results.json | jq '[.[] | select(.severity == 0)] | length'This counts error-severity findings. Pipe that number into a Slack notification, a PR comment, or a dashboard metric.
Practical CI snippet for GitHub Actions:
- name: Theme Check
run: |
shopify theme check --output json --fail-level error . > /tmp/tc.json
echo "Errors: $(jq '[.[] | select(.severity==0)] | length' /tmp/tc.json)"
env:
SHOPIFY_FLAG_STORE: ${{ secrets.SHOPIFY_FLAG_STORE }}
SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}
SHOPIFY_CLI_NO_ANALYTICS: 1Note: SHOPIFY_CLI_NO_ANALYTICS=1 silences telemetry. To suppress interactive prompts in CI, you also need SHOPIFY_FLAG_FORCE=1. Both are necessary for a clean, non-hanging pipeline run.
The Most Common Errors and How to Fix Them
Theme check surfaces a predictable set of recurring problems. Here are the ones that come up most in production pipelines:
MissingRequiredTemplateFiles
This fires when required templates like layout/theme.liquid, templates/product.json, or templates/gift_card.liquid are absent from the directory theme check is scanning. The most common cause is running the command from the wrong working directory, or checking out a partial repo in CI. Fix: confirm pwd is the theme root and that your git checkout step pulls all files, not a shallow clone.
ValidJSON / JSONSyntaxError
These two checks identify invalid JSON in theme files. JSONSyntaxError specifically identifies invalid JSON files in themes, and disabling it is not recommended. ValidJSON catches type mismatches inside {% schema %} tags and settings_schema.json, for example a placeholder field that should be a string but receives a number, or the inverse. Fix the type, then run shopify theme check --auto-correct to let the linter prettify schema JSON it can safely reformat.
SchemaJsonFormat
This check (Theme Check v1.x only) identifies improperly formatted JSON inside {% schema %} tags. Theme Check can correct this automatically using the --auto-correct flag, which prettifies the JSON data. This check is safe to disable in v2.x, where formatting is handled by the formatter instead.
Severity integer vs. string mismatch
The theme-check:recommended and theme-check:all configurations specify severities as integers (0, 1, 2). String forms (error, warning, suggestion) are equivalent and preferred for readability in your .theme-check.yml. Mixing the two in a custom config causes confusing output where severity appears to be ignored.
Why Theme Check Errors Also Break AI Search Visibility
This is the part most CI guides skip entirely.
Online Store 2.0 themes auto-emit Product, Offer, BreadcrumbList, and Organization JSON-LD on product pages. But that output is only as valid as the underlying Liquid and JSON that generates it. When a ValidJSON error corrupts a {% schema %} block in your product section, the rendered Product JSON-LD on that page can break silently: Liquid outputs an error string mid-JSON, which collapses the entire structured-data block.
The practical consequence:
- Google Rich Results: A malformed
Offerblock drops the product from price-comparison surfaces and Shopping eligibility. - AI engine citations: Missing identifier fields (GTIN, brand, MPN) prevent AI agents from matching your SKU across competing storefronts. A broken
AggregateRatingblock disqualifies the product from review-weighted AI recommendations. - BreadcrumbList errors: A
BreadcrumbListmissingpositionintegers isolates the product from category-level AI queries.
Running shopify theme check --output json --fail-level error catches the Liquid and schema-layer problems. But it does not validate the rendered JSON-LD that gets served to crawlers. You need a second pass against the live page output.
The two-layer audit approach:
- Theme Check (build time):
shopify theme check --output json --fail-level errorgates the deploy. - Rendered schema audit (runtime): Validate the actual JSON-LD emitted by the live URL using Google's Rich Results Test or a structured-data validator.
Shopify's documented CI pattern reflects this separation: theme check is the linter gate, shopify theme push --json is the deploy step, and schema validation is the post-deploy verification.
--fail-level Levels Compared
Choosing the right fail level is a tradeoff between strictness and noise:
| Fail level | What triggers exit code 1 | Best for |
|---|---|---|
error | Errors only | Production deploys (safe default) |
warning | Warnings + errors | Pre-production / staging gates |
suggestion | Everything | New themes, pre-launch quality bar |
style | Style issues + all above | Theme store submissions |
For most D2C stores, --fail-level error on the production branch and --fail-level warning on pull requests is the right combination. It blocks genuine breakage while keeping PR reviews from being overwhelmed by suggestion noise.
If you're submitting a theme to the Shopify Theme Store, Shopify's reviewers run --fail-level style, so your local gate should match.
Connecting Theme Health to AI Visibility
A clean theme check is necessary but not sufficient for AI search visibility. Here is what a production-ready Shopify theme CI pipeline looks like when you factor in both code quality and AI discoverability:
- Gate 1 (build):
shopify theme check --output json --fail-level errorblocks any deploy with error-severity Liquid or JSON issues. - Gate 2 (deploy):
shopify theme push --jsonpushes the verified theme and returns theme IDs as JSON for downstream steps. - Gate 3 (post-deploy): Validate rendered Product JSON-LD on key PDPs for missing GTIN, brand, MPN, and valid
Offer.availabilityvalues. - Gate 4 (weekly): Run prompt tests through ChatGPT and Perplexity to confirm AI engines are actually citing your products, not just crawling them.
Most Shopify teams have Gate 1 and Gate 2 in place. Gates 3 and 4 are where the AI search visibility gap opens up against competitors.
If your team wants to close that gap without building all four layers manually, AgentRank runs the 25-point AI-readiness audit and weekly prompt tests for you, so the results land in a dashboard your whole team can act on.
FAQ
What does --fail-level error actually mean in shopify theme check?
By default, Theme Check fails (returns exit code 1) when one or more issues with severity error are detected. The --fail-level error flag makes this explicit and is equivalent to running shopify theme check with no fail-level flag at all. You can raise the threshold to warning or suggestion to catch more issues in less critical environments.
Why does shopify theme check --output json produce no output file?
The --output json flag writes to stdout, not to a file. You need to redirect it: shopify theme check --output json . > results.json. If the command exits with code 1 before writing (for example, due to a missing Node version), the file will be empty or not created at all. Since CLI 4.0 (May 2026), Node 22.12+ is required.
Does passing shopify theme check guarantee my JSON-LD structured data is valid?
No. Theme Check validates your Liquid source files and schema JSON at build time, but it does not render and validate the JSON-LD that gets served to search engines and AI crawlers. A theme can pass all theme check rules and still emit broken Product structured data if catalog fields like GTIN or brand are missing in Shopify admin, or if a review app emits malformed AggregateRating markup at runtime.
Frequently asked questions
What does --fail-level error actually mean in shopify theme check?
By default, Theme Check fails and returns exit code 1 when one or more issues with severity error are detected. The --fail-level error flag makes this explicit and is equivalent to running shopify theme check with no fail-level flag at all. You can raise the threshold to warning or suggestion to catch more issues in less critical environments.
Why does shopify theme check --output json produce no output file?
The --output json flag writes to stdout, not to a file. You need to redirect it: shopify theme check --output json . > results.json. If the command exits before writing (for example, due to a missing Node version), the file will be empty or absent. Since Shopify CLI 4.0 in May 2026, Node 22.12 or higher is required.
Does passing shopify theme check guarantee my JSON-LD structured data is valid?
No. Theme Check validates Liquid source files and schema JSON at build time, but it does not render and validate the JSON-LD served to search engines and AI crawlers. A theme can pass all theme check rules and still emit broken Product structured data if catalog fields like GTIN or brand are missing in Shopify admin, or if a review app emits malformed AggregateRating markup at runtime.