Diagnose search and storefront problems

Start with what shoppers actually see. Don’t just update VIBE’s copy of your catalog again and again, or add a result rule and hope it helps: different symptoms come from different parts of VIBE, and the right fix depends on which part is actually broken.

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

2Choose areaInstallation, which products VIBE can show, your catalog, ranking, presentation, or tracking.

3Open the ownerGo to the admin page that controls that area.

4Make one fixApply the smallest change that matches what you found.

5Retest and recordRepeat the same steps and keep the evidence.

Use Search Preview to check your catalog and ranking without your theme in the way.

Use Installation when the storefront surface itself won't open or render.

For every problem you investigate, write down:

• Your store’s .myshopify.com domain.
• Your published theme and the theme you’re testing.
• The storefront URL, language, and market.
• The exact search, product, collection, filter, control, or rule involved.
• Desktop or mobile, and which browser.
• What you expected to see, and what you actually saw.
• Roughly when it happened.
• Any recent catalog, theme, rule, plan, or translation change, or a change to how VIBE reads your products.

Search does not open

The header search icon does nothing, opens your store’s old search, or opens a broken or empty panel.

Check, cheapest first:

1. Open Appearance > Installation.
2. Confirm the theme VIBE analyzed is your published theme.
3. Confirm the VIBE switch in your theme is turned on.
4. If it’s unclear whether the switch is on, select Check app embed.
5. Open Appearance > Quick search and confirm the selected search-box mode.
6. If you use your theme’s own search box, confirm Appearance shows it as ready.
7. If you use VIBE’s search box, switch temporarily to VIBE’s own cards to rule out a theme-card rendering problem.
8. Save the theme in the Theme Editor.
9. Hard refresh the storefront.
10. Test every header search icon, on both desktop and mobile.

What the result usually means:

• Switch off: an installation problem. Turn it on, save, and hard refresh.
• VIBE’s overlay works but your theme’s own search box doesn’t: a compatibility problem with that theme’s predictive search.
• The overlay opens but shows no products: a catalog, plan, request-limit, or exclusion problem, not an installation problem.
• One header icon works and another doesn’t: a theme selector or custom header VIBE isn’t detecting.

Don’t update VIBE’s copy of your catalog to fix a switch that’s off or a click that does nothing.

The full search page shows the old results

Quick search uses VIBE, but your store’s /search page still shows Shopify’s native results, a duplicate grid, or no VIBE interface at all.

Check, cheapest first:

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

The VIBE switch and the VIBE Search Page block are two separate pieces. One can be ready while the other is still missing, so check both.

A product is completely missing

The product doesn’t appear for its exact title, in Search Preview or on the storefront.

Check Shopify first, since it’s the cheapest place to look:

1. The product’s status is Active.
2. The product is published to the Online Store.
3. Shopify’s “hidden from search engines” setting is turned off.
4. The product is published to the market you’re testing.
5. The product has the title, handle, options, images, and inventory you expect.

Then check VIBE:

1. Open Sync and Index > Configuration.
2. Check your product, collection, and tag exclusions.
3. Check your out-of-stock setting.
4. Open Overview and confirm the latest update job isn’t pending, partial, cancelled, or failed.
5. Select Run full sync only if VIBE’s copy looks stale or the product came from a large import.
6. Search the exact title in Search Preview.
7. If the product appears there, check its Product sync status to see whether VIBE’s copy of it is current.
8. Check its Product data to see the actual content VIBE holds for it.

What the result usually means:

• Missing from Search Preview: the product isn’t in VIBE’s copy yet, or VIBE isn’t allowed to show it.
• Present in Search Preview but not on the storefront: check request-level settings, the theme surface, language or market, or rendering.
• Only appears when you search the exact title: a relevance or source-data problem, not a missing-product problem.

Don’t pin a product that isn’t in VIBE’s copy of your catalog yet, or that VIBE isn’t allowed to show.

A product ranks too low

The product appears, but below weaker results.

Check, cheapest first:

1. Run the exact search in Search Preview.
2. Compare the Score and Semantic score shown for the result.
3. Check the product’s title, description, type, tags, collections, vendor, and variants in VIBE’s copy.
4. Check how VIBE reads your products, under Sync and Index > Configuration.
5. Test again with every Explore control reset and no filters applied.
6. Search the Merchandising table for active rules that match this search.
7. Check rule priority and schedule.
8. Check whether the product is sold out and your Show last setting is active.
9. Decide whether this affects one search you care about, or many natural searches.

Choose the smallest fix that matches what you found:

• Fix the Shopify data when the product record itself is unclear.
• Update how VIBE reads your products when a broad range of natural searches are weak.
• Add a synonym when shoppers use different words for the same thing.
• Add a scoped boost for a business reason.
• Pin the product only when it must always hold a fixed position.
• Bury a competing product only when you have a deliberate business reason to.

Change one thing at a time and re-run the same search to see whether it worked.

Results are irrelevant for broad intent queries

Exact product names work, but phrases like minimal lamp for small desk return poor matches.

Check, cheapest first:

1. Look at several affected products in Shopify.
2. Confirm their descriptions and product types actually describe the product, not just boilerplate text.
3. Open Sync and Index > Configuration.
4. Review whether Balanced, More visual, or More text fits your catalog.
5. Confirm your product and context image sources are the right ones.
6. Select Analyze catalog again only after a real change to your catalog or how you present it.
7. Let that update, and any other queued update, finish.
8. Re-run the same set of natural-language searches.

If only one campaign search needs a business override, add a scoped rule instead. If many unrelated natural searches are weak, the shared catalog data or how VIBE reads your products is the real problem, and a rule won’t fix that.

A synonym does not work

1. Confirm your plan includes custom synonyms.
2. Open the rule and confirm it’s turned on.
3. Confirm the words are comma-separated and genuinely mean the same thing.
4. Confirm no higher-priority rule redirects or pins the same search first.
5. Test the exact search in Search Preview and on the storefront.
6. Check the rule’s usage numbers after some real storefront activity.

Avoid synonyms so broad they merge categories that should stay separate.

A redirect does not run

1. Confirm the rule is turned on and within its schedule.
2. Confirm your plan includes redirects.
3. Check the exact search phrase that should trigger it.
4. Confirm the destination is a valid page on your store, or the URL you intended.
5. Check for competing rules and their priority.
6. Test from quick search and the full search page.
7. Confirm your browser isn’t just showing a cached result from before.

Filters are missing

1. Set up filters in Shopify’s Search & Discovery app.
2. Confirm those fields actually have values on your products in Shopify.
3. Open Explore mode > Filters.
4. Select refresh.
5. Turn on the filters you want VIBE to use.
6. Confirm the affected products are in VIBE’s copy of your catalog.
7. Open the storefront’s full search page or Explore surface that supports filters.
8. Test the desktop sidebar or toolbar, and the mobile drawer.

Filters come from Shopify. Creating an Explore control doesn’t create a Shopify filter, so the two don’t substitute for each other.

An Explore control has little effect

1. Confirm Explore itself, and the control, are both turned on.
2. Confirm the control is within your plan’s active-control limit.
3. Check where the control sits in the storefront order.
4. Test it in Search Preview > Browse with no exact filters applied.
5. Move it from neutral to both extremes and compare results.
6. Use concepts that are clearly distinct and actually represented in your catalog.
7. Avoid using a control for something that’s really a fact, like size or color: use a filter for those instead.
8. Only regenerate your default controls if you actually want to replace the current set.

A subtle effect can be correct if your catalog has few products that differ on that concept. Look at the products in the result set before assuming the control is broken.

Similar or image search is weak

1. Confirm your plan includes the feature.
2. Confirm Similar, Taste, or Search by image is turned on for the surface you’re testing.
3. Open Sync and Index > Configuration > Image matching.
4. Confirm the product-image source you selected is correct.
5. Confirm your optional context images are set up as expected.
6. Open a few Shopify products and confirm those image fields hold real, accessible images.
7. Update VIBE’s copy of your catalog after changing an image source.
8. Test with a visually distinctive product or uploaded photo.

If the camera button is missing entirely, check your plan and feature settings before you troubleshoot relevance.

Your Vibe favorites disappear

Favorites live in the shopper’s own browser, not in your Shopify account, so they can disappear for reasons outside VIBE.

Check whether:

• The shopper cleared their browser’s site storage.
• They switched browser profile, device, or opened a private-browsing window.
• They moved between two different store domains.
• The browser’s privacy settings block local storage.
• The favorites list hit its saved-item limit.

Saving a favorite isn’t tied to a Shopify customer account.

Theme cards are malformed

1. Switch temporarily to VIBE’s own cards.
2. If VIBE’s cards look right, the results and ranking themselves are healthy, and the problem is how your theme renders cards.
3. Re-check your published theme.
4. Refresh your prepared cards in Installation > Fast loading.
5. Confirm your theme wasn’t recently published with a changed card design.
6. Test price, badges, variants, image, hover state, quick search, and the full page.
7. Keep VIBE’s cards active until your theme’s card design passes your own review.

Don’t change ranking or catalog data to fix an HTML or CSS rendering problem: they’re unrelated.

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 any text you need to override.
6. Open the storefront in that language and market.
7. Hard refresh and test quick search, the full page, filters, Explore, the no-results state, and Your Vibe.

If just one piece of text stays in the default language, find its exact location and translation entry before resetting the whole language.

Analytics is empty

1. Confirm VIBE is live on your published storefront.
2. Confirm real storefront searches happened in the 7, 30, or 90-day range you selected.
3. Remember Search Preview activity is excluded from Analytics.
4. Confirm your plan includes the tab you selected.
5. Give daily totals and paid-order matching time to finish, up to a day or two.
6. Check the System data panel on the Help page.

A headline card can show data while a detailed table stays empty, because each table needs its own kind of activity, and a minimum amount of it.

Revenue is lower than expected

1. Compare the search, click, cart-add, and purchase stages.
2. Confirm Shopify has marked the orders paid.
3. Confirm the product that was purchased matches the product VIBE credited.
4. Give the matching window and background processing time to settle.
5. Compare Direct VIBE, cart-confirmed, click/view, and control-group revenue separately.
6. Don’t compare VIBE’s numbers directly with another analytics tool until you’ve matched their definitions, time windows, currency, and order states to VIBE’s.

Shopper-visit usage looks high

1. Confirm your billing period and reset date.
2. Confirm whether a campaign brought in more real storefront traffic.
3. Remember one shopper is only deduplicated for 30 minutes, not for a full day.
4. Confirm bots aren’t being counted as human traffic in whatever tool you’re comparing against.
5. Check whether the comparison tool counts pageviews, users, or visits differently from VIBE.
6. Contact support with your store, time range, VIBE’s count, and how the other tool defines its count, if the gap still doesn’t make sense.

Escalate to support when

• Theme analysis keeps failing on your published theme.
• The VIBE switch is confirmed on, but VIBE never loads.
• The same products keep failing to finish updating.
• Search Preview and the storefront disagree, even with the same controls, filters, rules, language, and market.
• Your billing or plan access doesn’t match your approved Shopify subscription.
• The System data panel reports a service as degraded or down.
• A storefront error is affecting real 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