Search support guide

Diagnostic and troubleshooting reference for predictive search (Storefront API GraphQL backend with typo tolerance, REST fallback when no token), full search results page with typed tabs (Products / Articles / Pages), and the empty-state pack (did-you-mean, recent searches, popular searches, suggested collections).

For merchant setup and settings configuration, see the Search guide.

FAQ

Q1: Predictive search shows no results at all

Check in order:

Is the Storefront Access Token configured? Open DevTools → Console → paste the console diagnostic snippet. Look for token: true. If token: false, the token field in Theme Settings → Search is blank. Follow the token setup steps.
Is the REST fallback working? If token: false but predictiveSearchBackend: "rest", the fallback is active. Verify the store has published products by searching for a known product title. If results still don't appear, check that the store has published products visible in Shopify admin → Products.
Is the search drawer open? The <predictive-search> Custom Element only fetches after the drawer is open AND the input has at least 2 characters. Verify predictiveCE: true in the diagnostic snippet.
Network error? Open DevTools → Network → type in the search input → look for a POST to /api/2026-04/graphql.json (Storefront API) or a GET to /search/suggest.json (REST fallback). If the request returns 401 or 403, the token may be revoked or incorrect.

Q2: Typo tolerance not working (e.g., "shrt" does not return shirt results)

Typo tolerance requires the Storefront API token. Check:

window.uisceShopConfig.predictiveSearchBackend in the console diagnostic. If "rest", you are on the REST fallback — typo tolerance is not available via /search/suggest.json.
If predictiveSearchBackend: "storefront-api" but typo results are missing, verify the Storefront API version in window.uisceShopConfig.storefrontApiVersion — it should be 2026-04 or later. Earlier versions may have different typo-tolerance behavior.
Some very short tokens (3 characters or fewer) do not trigger typo tolerance even in the Storefront API — this is expected. Use 4+ character queries to test typo tolerance.

Q3: Recent searches not appearing in the predictive empty state

Recent searches are stored in versioned localStorage via UisceShopperState. They are recorded when the shopper submits a search form (not on each keystroke).

Check:

window.UisceShopperState exists (diagnostic snippet confirms shopperState: true)
recentSearchesCount in the diagnostic snippet — should be > 0 after submitting at least one search
Recent searches respect the 5-entry cap (oldest is pruned when a 6th is added)
localStorage is available — if the shopper is in a private/incognito window or has localStorage blocked, recent searches are unavailable (feature degrades gracefully — block is hidden)

Q4: Popular searches block not appearing

Popular searches are rendered server-side from the Header section settings (popular_searches_1..5). They are only visible in the predictive empty state (when the input is focused but empty or has 0 results).

Check:

Are any popular_searches_* settings populated in the Header section in the theme editor?
The popular searches block is shown when the input is focused AND empty (before typing). Type a query → clear it → focus the input again to trigger the empty state.
If the block still doesn't show, verify data-popular-searches attribute on the <predictive-search> element in DevTools → Elements.

Q5: Typed tabs not appearing on search results page

Typed tabs (Products / Articles / Pages) only appear when the corresponding type has at least one result. If only products are found, only the Products tab appears.

Check:

Does your store have published blog articles? Articles only appear in search results if at least one is published.
Does your store have published pages? Same logic applies to the Pages tab.
Try a generic search term like "about" or your store name — this often surfaces pages + articles.
Verify tabsCE: true in the diagnostic snippet. If tabsCE: false, the <search-srp-tabs> Custom Element was not registered — this is a JavaScript load failure.

Q6: URL does not update when switching tabs

The <search-srp-tabs> Custom Element uses the History API (history.pushState) to update the URL with ?type=products, ?type=articles, or ?type=pages. This requires:

JavaScript is enabled
The browser supports history.pushState (all modern browsers)

If the URL is not updating, open DevTools → Console → look for JavaScript errors. The CE should update the URL and the aria-selected state on tab buttons simultaneously.

Q7: Filters on the search SRP drop when switching tabs

This is by design. Collection filters (facets) are tab-scoped — switching from Products to Articles drops the product filters because article filtering uses a different filter set (tags, dates) vs product filtering (variants, collections). Per RESEARCH.md Pitfall 3: "Tab swap drops filter params — tab switch intentionally navigates to the new tab's base URL without preserving filters from the previous tab."

Q8: "Viewport remount not supported" — what does this mean?

This is a known limitation documented in Phase 06.3 and carried forward: the predictive search drawer uses a one-shot loaded flag — once loaded, it does not reload on viewport changes (e.g., switching from mobile to desktop breakpoint). The drawer continues to function correctly after viewport changes; the limitation only affects the initial load state. This is a Phase 7 polish item.

Decision tree: "Why is search not working?"

Predictive search shows nothing

Predictive search shows nothing
│
├─ Is JavaScript enabled?
│   No → search form still works (native /search endpoint)
│   Yes → continue
│
├─ Is the input focused with ≥ 2 characters?
│   No → by design (min 2 chars trigger)
│   Yes → continue
│
├─ Check console diagnostic: token: true?
│   false → Storefront token not set → follow token setup guide
│   true → continue
│
├─ Check console diagnostic: predictiveSearchBackend?
│   "rest" → token set but Storefront API error → verify token not revoked
│   "storefront-api" → continue
│
├─ Network tab: POST to /api/2026-04/graphql.json returning 200?
│   401/403 → token invalid or revoked → recreate token
│   200 → response has results?
│       No results in response → store may have no matching products
│       Yes results → JS render bug → open a support issue with console output

Typed tabs not appearing

SRP shows only Products tab (or no tabs)
│
├─ Does the search query return articles?
│   No → publish blog articles in Shopify admin
│   Yes → continue
│
├─ Does the search query return pages?
│   No → create and publish a page in Shopify admin
│   Yes → continue
│
├─ Check diagnostic: tabsCE: true?
│   false → JS load failure → check browser console for errors
│   true → tab logic OK but results filtered?
│       Check <search-srp-tabs> data-active-tab attr in DevTools

Console diagnostic snippet

Paste into browser DevTools Console on any storefront page. Read-only, adds zero theme code.

(() => {
  const r = {
    token: !!window.uisceShopConfig?.storefrontAccessToken,
    tokenPrefix: window.uisceShopConfig?.storefrontAccessToken?.slice(0, 8) ?? null,
    apiVersion: window.uisceShopConfig?.storefrontApiVersion,
    predictiveSearchBackend: window.uisceShopConfig?.predictiveSearchBackend ?? 'not-set',
    predictiveCE: !!customElements.get('predictive-search'),
    tabsCE: !!customElements.get('search-srp-tabs'),
    shopperState: !!window.UisceShopperState,
    recentSearchesCount: window.UisceShopperState?.all('recent-searches')?.length ?? null,
  };
  console.table(r);
})();

What to look for:

Field	Expected value	What it means if wrong
`token`	`true`	`false` → token not set; typo tolerance unavailable
`tokenPrefix`	First 8 chars of your token	`null` → token not set; verify Theme Settings
`apiVersion`	`2026-04 or later`	Older version → may have different API behavior
`predictiveSearchBackend`	`"storefront-api"`	`"rest"` → token absent or Storefront API error
`predictiveCE`	`true`	`false` → predictive-search CE not registered (JS load failure)
`tabsCE`	`true`	`false` → search-srp-tabs CE not registered (JS load failure)
`shopperState`	`true`	`false` → shopper-state.js not loaded; recent searches unavailable
`recentSearchesCount`	Integer ≥ 0	`null` → shopperState not initialized or localStorage blocked

To confirm which backend is active at runtime, check window.uisceShopConfig.predictiveSearchBackend. This is set by predictive-search.js at initialization based on whether a valid token is present.

Curl cheat-sheet

Replace {store} with your storefront domain (e.g., uisce.sionnach.solutions) and {token} with your Storefront Access Token.

Dev stores are password-protected. Capture the _shopify_essential cookie first:

bash

# Get CSRF token
curl -s -c cookies.txt https://{store}/password -o /tmp/pw.html
CSRF=$(grep -o 'name="authenticity_token" value="[^"]*"' /tmp/pw.html | head -1 | sed 's/.*value="//;s/"//')

# Submit password
curl -s -c cookies.txt -b cookies.txt \
  --data-urlencode "form_type=storefront_password" \
  --data-urlencode "authenticity_token=${CSRF}" \
  --data-urlencode "password={preset-password}" \
  -L "https://{store}/password" -o /dev/null

# Now add -b cookies.txt to all subsequent curl commands

Test Storefront API predictiveSearch query

bash

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Storefront-Access-Token: {token}" \
  -d '{"query":"{ predictiveSearch(query:\"shrt\", limit:4, types:[PRODUCT]) { products { title } queries { text } } }"}' \
  https://{store-myshopify-domain}/api/2026-04/graphql.json | jq .

Expected: data.predictiveSearch.products array with products matching "shirt" (typo-corrected). Empty array → no products, or token lacks storefront access.

Test REST fallback (no token)

bash

curl -s "https://{store}/search/suggest.json?q=shirt&resources[type]=product&resources[limit]=4" | jq .

Expected: resources.results.products array. Works without a token; no typo tolerance.

Deprecation note on /search/suggest.json

/search/suggest.json continues to work in Shopify 2026-04 but is the legacy endpoint. It does NOT support typo tolerance, query suggestions, or pages/articles in the same response format as the Storefront API. Use the Storefront API predictiveSearch mutation for full feature support.

Verify search SRP empty state (suggested collections)

bash

curl -s -b cookies.txt \
  "https://{store}/search?q=xyzzy123notaword&type=product" | \
  grep -c "suggested-collections\|empty-state"

Expected: non-zero count confirming the empty-state block renders.

Google Rich Results Test URL template

For testing article structured data on a production store (no password protection):

https://search.google.com/test/rich-results?url={article_url_encoded}

For password-protected dev stores, use HTML-paste mode:

bash

curl -s -b cookies.txt https://{store}/blogs/news/{article-handle} > /tmp/article.html
# Then paste /tmp/article.html content into:
# https://search.google.com/test/rich-results (click "Code" tab)

Or validate the JSON-LD directly:

bash

curl -s -b cookies.txt https://{store}/blogs/news/{article-handle} | \
  python3 -c "
import re, json, sys
html = sys.stdin.read()
blocks = re.findall(r'<script[^>]*type=[\"'\''']application/ld\+json[\"'\'''][^>]*>(.*?)</script>', html, re.DOTALL)
for b in blocks:
    if 'BlogPosting' in b:
        try:
            d = json.loads(b.strip())
            print('@type:', d.get('@type'))
            print('mainEntityOfPage:', bool(d.get('mainEntityOfPage')))
            print('articleSection:', bool(d.get('articleSection')))
            print('inLanguage:', bool(d.get('inLanguage')))
            print('wordCount:', bool(d.get('wordCount')))
        except Exception as e:
            print('JSON error:', e)
"

Need more help?

File a GitHub issue with the console-snippet output + browser/OS + preset name.
See the Search guide for settings documentation.

Search guide — configuration walkthrough
Blog and article support — audio, JSON-LD, author bio, social share
Product page support
Collection page support
Support form — submit a ticket if the above does not resolve your issue

Search support guide ​

FAQ ​

Q1: Predictive search shows no results at all ​

Q2: Typo tolerance not working (e.g., "shrt" does not return shirt results) ​

Q3: Recent searches not appearing in the predictive empty state ​

Q4: Popular searches block not appearing ​

Q5: Typed tabs not appearing on search results page ​

Q6: URL does not update when switching tabs ​

Q7: Filters on the search SRP drop when switching tabs ​

Q8: "Viewport remount not supported" — what does this mean? ​

Decision tree: "Why is search not working?" ​

Predictive search shows nothing ​

Typed tabs not appearing ​

Console diagnostic snippet ​

Curl cheat-sheet ​

Capture auth cookie (dev stores only) ​

Test Storefront API predictiveSearch query ​

Test REST fallback (no token) ​

Deprecation note on /search/suggest.json ​

Verify search SRP empty state (suggested collections) ​

Google Rich Results Test URL template ​

Need more help? ​

Related docs ​

Search support guide

FAQ

Q1: Predictive search shows no results at all

Q2: Typo tolerance not working (e.g., "shrt" does not return shirt results)

Q3: Recent searches not appearing in the predictive empty state

Q4: Popular searches block not appearing

Q5: Typed tabs not appearing on search results page

Q6: URL does not update when switching tabs

Q7: Filters on the search SRP drop when switching tabs

Q8: "Viewport remount not supported" — what does this mean?

Decision tree: "Why is search not working?"

Predictive search shows nothing

Typed tabs not appearing

Console diagnostic snippet

Curl cheat-sheet

Capture auth cookie (dev stores only)

Test Storefront API predictiveSearch query

Test REST fallback (no token)

Deprecation note on /search/suggest.json

Verify search SRP empty state (suggested collections)

Google Rich Results Test URL template

Need more help?

Related docs