Troubleshooting Easy Brand Page

Most Easy Brand Page problems have one of three causes: missing or inconsistent vendor data on your products, a stale sync, or a theme block that isn't placed/saved correctly. This page walks through the common ones.

The directory is empty

Symptoms: you added the block, but the storefront shows no brands (or an empty placeholder).

Most common causes:

1. No vendor on your products. Open any product in Shopify admin, scroll to "Product organisation", check the Vendor field. If empty, brand sync sees nothing.
2. You haven't run a scan yet. Open Brands and click Scan now. Wait for completion.
3. The block was added but never saved. Open the theme editor, click into the section, click Save. See the theme block guide.
4. The block was added to a draft theme, not the live theme. Confirm you're customising the published theme, not a duplicate.

A specific brand is missing

Symptoms: most brands appear, but one or more are missing from the directory.

Check, in order:

1. Is the vendor spelled the same on every product? Inconsistent capitalisation or extra spaces (e.g. "Nike " with a trailing space) creates separate brands. Fix the vendor field across affected products and re-scan.
2. Has the vendor been excluded? Open the Brands page and check the Visibility column - it might be marked Excluded.
3. Was the brand removed from your list? A removed brand is off your storefront and out of the All view. On the Brands page, click the filter button next to the search bar and pick Removed brands. If it's there, open that row's Edit menu and choose Restore brand.
4. Are all the vendor's products out of stock? If yes, the brand may be hidden via the "Out of stock brands" setting. Restock a product, or change the setting in Settings.
5. Has a scan run since you added the vendor? Click Scan now.

A brand's link goes to the wrong place

Symptoms: clicking a brand card takes the customer to an unexpected URL.

Check, in order:

1. Does an unrelated collection share the brand name? The auto-matcher prefers exact handle matches. If you have a vendor "Nike" and an unrelated collection with handle nike, the matcher picks the collection. Either rename the collection, or map the brand to the right collection by hand from its Collection mapping cell on the Brands page.
2. Is the search URL template customised? Check the Search URL template in Settings. The default is /collections/vendors?q=%brand%. If you've changed it, double-check the pattern still works on your storefront.

See the collection matcher logic for the full decision order.

Tag pills aren't showing

Symptoms: you added tags to brands, but no filter pills appear on the storefront.

Check, in order:

1. Are you on the Plus plan? Tags are a Plus feature - on the free plan no pills are published.
2. Is "Show tag filter pills" on? Open the Brand Page block in the theme editor and check the Filters group. The toggle is on by default, but it may have been switched off.
3. Is "Only show brands with this tag" set? When a block is pinned to a single tag, the pills are hidden on purpose.
4. Does at least one visible brand have the tag? Pills only appear once a visible brand carries a tag. Excluded brands, brands locked by the free-plan cap, and brands hidden as out of stock don't count.
5. Did the change publish? If a save on the Brands page failed to reach the storefront, a banner with a Re-sync to storefront button appears there - click it to retry.

See how brand tags work for the feature end to end.

A brand is missing from the storefront, or clicking a pill shows nothing

Symptoms: a brand shows in the app but never appears in the storefront directory - or a filter pill exists but clicking it reveals no brands.

The most common cause: the brand's products aren't visible on your Online Store. The app reads ALL your products through Shopify's Admin API, including drafts and products not published to the Online Store sales channel. Your storefront theme can only render vendors of products that are Active AND published to the Online Store channel. A brand whose products are drafts, archived, or published only to other channels (like POS) exists in the app but has no card on the page - so a pill pointing only at such brands reveals nothing.

The app now surfaces this state for you: brands in it carry a small alert icon on their image on the Brands page (hover it for the explanation), and the view filter next to the search bar has a Not on storefront option that lists them all. The marker appears after the next scan.

Check, in order:

1. Product status: open one of the brand's products in Shopify admin - is it Active (not Draft or Archived)?
2. Sales channels: on the product page, check "Publishing" / sales channels - is Online Store included?
3. Does the brand still have products at all? The app keeps a brand's row after its last product is deleted or re-vendored (so your mappings and tags survive), but a brand with zero products can't appear on the storefront. Its product count shows 0 on the Brands page.
4. Is the brand excluded, out of stock, or beyond the free-plan cap? Any of those hides it by design.

A logo upload fails

Symptoms: uploading a brand logo fails with a message telling you to close and reopen the app.

Cause: logo uploads store images in your store's own Shopify Files, and that needs a new Shopify permission (managing files). Shopify asks you to approve it the next time you open the app after the update that added logos. Until you approve, uploads fail.

Fix: close the app, open Easy Brand Page again from your Shopify admin, and approve the permission when Shopify asks. Then retry the upload.

Also check the file itself: PNG, JPG, WEBP, or GIF, up to 5 MB. And on the free plan, brands locked by the 30-vendor cap can't edit logos. See uploading brand logos for the full feature.

The brand slider shows names instead of logos

That's by design. Brands with an uploaded logo show the logo; brands without one show their name as text, so the slider works before any logos exist. Upload logos from the Edit menu on each brand's row on the Brands page and the names turn into logos on their own.

If the slider shows brands you didn't pick: check the block's Brands to show setting in the theme editor (Featured brands, One tag, or All brands) and its Number of brands setting. See the Brand slider block for every setting.

Brand counts are wrong

Symptoms: a brand shows "5 products" on the directory but you have 8 products from that vendor.

Cause: the scan runs against active products only. Draft and archived products don't count. If 3 of your 8 products are draft, the count of 5 is correct.

To verify: in Shopify admin Products, filter by your vendor, then filter Status = Active.

The storefront still shows old data

Symptoms: you ran a scan, but the directory hasn't updated on the storefront.

Causes (in order):

1. Browser cache. Hard refresh: Cmd-Shift-R on Mac, Ctrl-Shift-R on Windows.
2. Theme cache / CDN. Shopify caches Liquid output. Wait a minute and refresh.
3. The scan didn't actually complete. Open the Brands page and check the "Last scanned" timestamp.
4. You're waiting for auto-sync. Product changes are grouped before one re-scan runs, so the automatic update can be a few minutes behind (up to about 30 after a big import). The "Last scanned" line shows "(auto-sync)" once the automatic scan has run. Click Scan now to skip the wait.

The sync mechanic is explained in brand syncing.

Search doesn't filter

Symptoms: typing in the search box doesn't reduce the brand list.

Causes:

1. JavaScript is disabled on the storefront (very rare). Search is client-side; without JS it doesn't work.
2. A third-party theme conflict. If your theme heavily customises script loading, the small inline script the block uses can sometimes be blocked. Try a different theme to confirm.
3. Vendor names contain unusual characters. Search matches against the rendered vendor name. If your vendors contain HTML entities (e.g. encoded ampersands), search may not match them. Clean up the vendor field on your products.

A-Z filter is missing letters or grouping wrong

Symptoms: brands starting with accented letters don't appear under their expected letter, or numeric brands appear scattered.

Open Settings and review:

• Standardize accents. If off, accented letters group separately - turn it on for unified grouping.
• Special character group symbol. Sets the label for non-Latin starts.
• Group numeric brands. If off, every digit is its own group.
• Numeric group symbol. The label for grouped numeric brands.

I uninstalled the app and the directory disappeared

This is expected. When you uninstall:

1. The block stops rendering because the metafield it reads is removed after Shopify's 48-hour grace period.
2. Reinstalling within 48 hours restores everything.
3. After 48 hours, you'd need to re-scan to rebuild the data.

Your products, collections, and theme are never modified by Easy Brand Page, so they're unaffected.

Performance issues on very large stores

Symptoms: the first scan on a store with 50k+ products takes a long time.

This is normal. The scan paginates through every product to extract vendors and inventory. It runs server-side so you can leave the page; only one scan can run per shop at a time (with a 30-minute auto-expiry on the lock if something gets stuck).

Subsequent scans are not faster - Easy Brand Page reads every product on every scan. Auto-sync helps here: it groups bursts of product changes and runs one scan for the whole batch, so you rarely need to trigger scans yourself.

Still stuck?

Open Get help in the app to browse the guides or email support - or write directly to support@upsellshark.com with your shop URL and a screenshot.