Diagnose search and storefront problems

Start with the shopper-visible symptom. Do not begin by repeatedly syncing or adding a merchandising rule. Different symptoms belong to different layers of VIBE.

1Capture symptomRecord exact query, URL, product, theme, market, language, and device.

2Choose layerInstallation, eligibility, indexed data, ranking, presentation, or tracking.

3Inspect ownerOpen the admin page that controls that layer.

4Make one fixApply the smallest change that matches the evidence.

5Retest and recordVerify the same reproduction path and retain evidence.

Use Preview to isolate catalog and ranking behavior from theme rendering.

Use Installation when the storefront surface does not open or render as expected.

For every investigation, record:

• Store .myshopify.com domain.
• Published theme and tested theme.
• Storefront URL, language, and market.
• Exact query, product, collection, filter, control, or rule.
• Desktop or mobile and browser.
• Expected result and actual result.
• Approximate time.
• Recent catalog, profile, theme, rule, plan, or translation changes.

Search does not open

Symptom

The header search icon does nothing, opens the old theme search, or opens a broken/empty panel.

Checks

1. Open Appearance > Installation.
2. Confirm the expected theme is the published theme.
3. Confirm Theme app embed is enabled.
4. If status is unknown, select Check app embed.
5. Open Appearance > Quick search and confirm the selected search-box mode.
6. If using the theme’s search box, confirm theme analysis marks instant search ready.
7. If using VIBE’s search box, temporarily choose the standard VIBE cards to isolate theme-card rendering.
8. Save the theme in Theme Editor.
9. Hard refresh the storefront.
10. Test every header search entry point on desktop and mobile.

Interpretation

• Embed off: installation issue.
• VIBE overlay works but theme search does not: theme predictive-search compatibility issue.
• Overlay opens but products are empty: index, plan, request, or catalog issue.
• One header icon works and another does not: theme selector or custom header issue.

Do not run a product sync to repair a missing app embed or click handler.

The full search page shows the old results

Symptom

Quick search uses VIBE, but /search shows Shopify native results, duplicate grids, or no VIBE interface.

Checks

1. Open Appearance > Installation.
2. Review Search page status.
3. Open the Theme Editor for the published theme.
4. Open the search template.
5. Add or confirm the VIBE Search Page app block.
6. Remove unintended duplicate result sections only if the theme configuration calls for it.
7. Save the theme.
8. Return to VIBE and run the search-page check.
9. Open /search?q=<known-product> directly.
10. Test query, filters, sorting, pagination, and product links.

The app embed and Search Page block are separate integrations. One can be ready while the other is missing.

A product is completely missing

Symptom

The product does not appear for its exact title in Preview or the storefront.

Shopify checks

1. Product status is Active.
2. Product is published to the Online Store.
3. seo.hidden or equivalent search-engine hiding is not active.
4. Required market publication is active.
5. The product has the expected title, handle, options, images, and inventory.

VIBE checks

1. Open Sync and Index > Configuration.
2. Check product, collection, and tag exclusions.
3. Check out-of-stock handling.
4. Open Overview and confirm the latest job is not pending, partial, cancelled, or failed.
5. Run a full sync only if the record is stale or the product came from a broad import.
6. Search the exact title in Search Preview.
7. Inspect Product sync and indexed Product data if the product appears.

Interpretation

• Missing from Preview: eligibility or index problem.
• Present in Preview but not storefront: request modifiers, theme surface, language/market, or rendering problem.
• Appears only after exact title: relevance or source-data quality problem.

Do not pin a product that is not eligible or indexed.

A product ranks too low

Symptom

The product appears but is below weaker results.

Checks

1. Run the exact query in Search Preview.
2. Compare overall and semantic scores.
3. Inspect indexed title, description, type, tags, collections, vendor, and variants.
4. Check the active search-profile preference.
5. Test with controls reset and no filters.
6. Search the Merchandising table for matching active rules.
7. Check rule priority and schedule.
8. Check whether the product is sold out and Show last is active.
9. Decide whether the issue affects one deliberate campaign or many natural queries.

Choose the fix

• Correct Shopify data when the record is unclear.
• Refresh the search profile when a broad class of intent queries is weak.
• Add a synonym for equivalent shopper language.
• Add a scoped boost for a business preference.
• Pin only when a fixed position is required.
• Bury competing products only when there is a deliberate merchandising reason.

Change one layer and repeat the same query set.

Results are irrelevant for broad intent queries

Symptom

Exact names work, but phrases such as minimal lamp for small desk return poor matches.

Checks

1. Review several affected products in Shopify.
2. Confirm descriptions and product types contain meaningful product information.
3. Open Sync and Index > Configuration.
4. Review Balanced, More visual, or More text.
5. Confirm the intended product and context image sources.
6. Select Analyze catalog again after a real catalog-model change.
7. Allow the profile and required sync to complete.
8. Re-run a fixed set of intent queries.

If only one campaign query needs a business override, use a scoped rule. If many unrelated intent queries are weak, fix the shared data/profile layer.

A synonym does not work

1. Confirm the plan includes custom synonyms.
2. Open the rule and check that it is active.
3. Confirm the intended words are comma-separated and genuinely equivalent.
4. Confirm another higher-priority rule is not redirecting or pinning the same trigger.
5. Test the exact trigger in Preview and storefront.
6. Check the rule’s usage metric after real storefront activity.

Avoid overly broad synonyms that collapse distinct categories.

A redirect does not run

1. Confirm the rule is active and within its schedule.
2. Confirm the plan includes redirects.
3. Check the exact trigger phrase.
4. Verify the destination is a valid relative storefront path or intended URL.
5. Check competing rules and priority.
6. Test from quick search and the full page.
7. Confirm the browser was not already on a stale cached result state.

Filters are missing

1. Configure filters in Shopify Search and Discovery.
2. Confirm the fields have product values in Shopify.
3. Open Explore mode > Filters.
4. Select the refresh action.
5. Enable the synchronized filters intended for VIBE.
6. Confirm affected products are indexed.
7. Open the storefront full page or Explore surface that supports filters.
8. Test desktop sidebar/toolbar and mobile drawer.

Filters are sourced from Shopify. Creating a VIBE semantic control does not create a Shopify filter.

An Explore control has little effect

1. Confirm Explore and the control are enabled.
2. Confirm the control is within the plan’s active limit.
3. Check the control’s storefront order.
4. Test it in Search Preview > Browse with no exact filters.
5. Move it from neutral to both extremes.
6. Use concepts that are distinct and represented in the catalog.
7. Avoid factual options better modeled as filters.
8. Regenerate defaults only if you intend to replace the default set.

A subtle control can be correct when the catalog has few products that differ on that concept. Review the eligible result set before rewriting it.

Similar or image search is weak

1. Confirm the plan enables the feature.
2. Confirm Similar, Taste, or Search by image is enabled for the intended surface.
3. Open Sync and Index > Configuration > Image matching.
4. Verify the selected product image position or metafield.
5. Verify optional context images.
6. Open several Shopify products and confirm those fields contain valid, accessible images.
7. Re-sync after changing image sources.
8. Test a visually distinctive seed or upload.

If the camera button is missing entirely, diagnose plan and feature visibility before relevance.

Your Vibe favorites disappear

Your Vibe favorites are stored in the shopper’s browser.

Check whether:

• Site storage was cleared.
• The shopper changed browser profile, device, or private-browsing session.
• The test moved between different store domains.
• Browser policy blocks local storage.
• The item exceeded the current saved-favorites cap.

Saving is not automatically tied to a Shopify customer account.

Theme cards are malformed

1. Switch temporarily to VIBE cards.
2. If VIBE cards work, the search result and ranking path is healthy.
3. Re-check the published theme.
4. Refresh prepared cards in Installation > Fast loading.
5. Confirm the theme was not recently published or its card snippet changed.
6. Test price, badges, variants, image, hover state, quick search, and full page.
7. Keep VIBE cards active until the theme-card mode passes QA.

Do not change relevance or catalog data to repair HTML/CSS rendering.

Translations are missing

1. Confirm the language is published in Shopify.
2. Open Appearance > Translations.
3. Select Sync languages.
4. Choose the exact language.
5. Save the required overrides.
6. Open the storefront in that locale and market.
7. Hard refresh and test quick search, full page, filters, Explore, no-results, and Your Vibe.

If one string remains in the default language, identify its exact surface and translation key before resetting the whole locale.

Analytics is empty

1. Confirm VIBE is live on the published storefront.
2. Confirm real storefront searches occurred in the selected 7, 30, or 90 days.
3. Remember that Search Preview is excluded.
4. Confirm the current plan exposes the selected advanced tab.
5. Allow daily rollups and paid-order attribution time to complete.
6. Check system data on the Help page.

Headline cards can have data while a detailed table is empty because each table depends on its own event type and minimum activity.

Revenue is lower than expected

1. Compare search, click, cart-add, and purchase stages.
2. Confirm Shopify marks the orders paid.
3. Confirm the purchased product matches the attributed product.
4. Allow the attribution window and worker processing to settle.
5. Compare Direct VIBE, ATC-confirmed, Click/view, and control revenue.
6. Do not compare VIBE attribution directly with a different analytics tool until definitions, windows, currency, and order states are aligned.

Session usage looks high

1. Confirm the billing period and reset date.
2. Confirm whether a campaign increased real storefront visits.
3. Remember that one active identifier is deduplicated for 30 minutes, not for a full day.
4. Confirm bots are not being mistaken for human traffic in another system.
5. Check whether the comparison tool counts pageviews, users, or sessions differently.
6. Contact support with the store, time range, VIBE count, and comparison definition when the gap remains material.

Escalate to support when

• Theme analysis repeatedly fails on the published theme.
• App embed is verified but VIBE never loads.
• The same eligible products repeatedly fail Finish sync.
• Search Preview and storefront disagree with controls, filters, rules, language, and market aligned.
• Billing or plan access disagrees with the approved Shopify subscription.
• System data reports a degraded or down service.
• A storefront error affects shoppers.

Include the investigation record from the top of this guide.

Related guides

• How VIBE fits together
• Search relevance and ranking
• Admin control reference
• Catalog and theme change playbook
• Help and support