Skip to content

Troubleshooting ​

Symptom by symptom. Start with what you're seeing, not with what you think the cause is.

A block isn't showing on the storefront ​

This is the most common report, and there are only a handful of reasons a block stays hidden. Work through them in this order: they follow the order the plugin itself checks things, starting with the quickest to rule out. It's the same list as the Recommendation Manager's, written from the symptom side.

One thing to know first: a block that has nothing to show doesn't render at all. There's no empty box, no heading with nothing under it, and no error. That's deliberate, but it means "missing" can have several causes.

Check the Live Preview first

Open the Recommendation in the builder. The Live Preview runs the same engine as the storefront and names several of these causes directly, such as "Another placement wins this location."

1. It's Inactive, or has no placement ​

Only Active Recommendations render. Check the Status column on Recommend → All Recommendations, and click the switch to activate it.

A save can also leave a Recommendation Inactive on purpose. If it isn't complete enough to go live, the toast says "Saved as inactive — to activate, fix this: …" and names what to fix. A duplicate is always "saved as inactive" too. And a Recommendation with no placement can't show anywhere: the builder says "No placement, so this recommendation cannot show anywhere."

2. You're looking at the wrong page ​

A block only appears on the kind of page its Show On setting reads (Product, Category, Cart, and so on), at the Position On Page you picked in Step 1. A Product block placed at Product page · After tabs will never appear on a category archive.

The shortcode and the Shaped Recommend block are the same: they only show a Recommendation whose position is set to Custom placement · Shortcode or Custom placement · Block. Pasting a shortcode for a Recommendation placed at Cart · After totals shows nothing.

3. Your theme doesn't fire that position's hook ​

Each position hangs off a WooCommerce hook. If your theme moves or removes that hook, or the page is built from blocks that never fire it, the position simply never runs. See the block lands in the wrong place and nothing renders on a block theme.

4. It needs Pro, and Pro isn't active ​

A placement that uses a Pro feature (a Pro filter, sort, display, position or condition) stops rendering while Pro is inactive. The preview says "This placement uses a Pro feature that is not active on this store." Your configuration is kept exactly as it was, so activating Pro brings it straight back.

5. A display condition isn't true for you ​

Conditions on Step 3 · Display Conditions decide whether the block shows at all. If the block only shows on mobile, to guests Pro, or above a cart total Pro, you won't see it while you're logged in on a desktop with an empty cart.

Test in a private window, and set up the condition's positive case on purpose: put enough in the cart, or switch to a phone.

Conditions fail closed. If the plugin can't evaluate a condition, the block doesn't render. A Viewing Category Pro condition with no category selected never matches, and the builder warns you about it.

6. No products matched ​

If the preview says "Nothing matches yet — no product satisfies these filters against the sample data", your filters are too narrow. Common culprits:

  • A Price range that no product falls into
  • Several filter groups combined with AND that no single product satisfies
  • A category with too few products once your other filters have run
  • Products that can't be bought: unpublished, hidden from the catalogue, out of stock (if your store hides out-of-stock items) or not for sale. These are dropped before rendering.

A Bundle box Pro needs at least two simple products. It only includes simple products, so a pool of variable products leaves it short, and it's held back rather than shown as a "bundle" of one.

Remove filters one at a time until the preview fills, then add them back one by one.

The preview shows one example page

The preview resolves against one example product, category or cart, and the banner above it names which one. A block that fills on that example can still come up empty on a product in a small category, so check your sparsest category on the real storefront too.

7. Another Recommendation won the slot ​

Two Recommendations at the same position can't both render there. One wins and the other is held back. The preview says "Another placement wins this location."

The higher one in your priority order wins. On the free plugin, that's the order you created them in, oldest first. With Pro Pro, you set the order by dragging rows on All Recommendations. Or move one of them to a different position.

8. A limit held it back ​

This only happens if you've switched a limit on under Settings → Recommendation Manager. Both ship off.

  • Limit blocks per page. Once the page has shown its quota of blocks, later ones are held back.
  • Limit recommendations per session. Once a shopper has seen that many blocks in one visit, they stop seeing more until their next visit. A visit ends after 30 minutes without activity. This is the one that makes blocks "stop working" while you test: you browse ten products and the block disappears. Open a private window to start a fresh visit.

A Recommendation held back by either limit gets a Limit reached chip on All Recommendations. Hover the chip to see which limit did it.

9. No repeated products took all its products ​

With No repeated products switched on (it's off by default), a product shown by an earlier block on the page can't appear again. If every product this block wanted was already taken, it has nothing left and is held back. The preview says "Everything this would show is already shown by an earlier placement on the page."

Widen this block's pool, show fewer products in the earlier block, or switch the setting off.

10. The shopper closed it Pro ​

A popup that a shopper dismisses stays closed for them for the rest of the day. That's working as designed. Test in a fresh private window.

Not missing, just grey? ​

If you can see an empty grey shape where the block should be, the block was placed but never filled in. That's a different problem: see the next section.

A block shows as a grey placeholder and never fills in ​

The page rendered a placeholder, but the request that fills it in didn't complete.

  1. Check the browser console for a failed request to /wp-json/sprcm/v1/hydrate.
  2. An optimisation plugin is probably delaying JavaScript. "Delay JS until interaction" and aggressive script deferral both break this. Exclude the plugin's storefront script.
  3. A security plugin or firewall may be blocking the REST API. Check that /wp-json/ loads at all.
  4. An HTML minifier may be stripping data attributes, which the block needs to identify itself. It's rare, but it happens on the most aggressive settings.

Test with your cache and optimisation plugins switched off. If it works then, switch them back on one at a time to find the culprit.

Two related-products boxes on the product page ​

WooCommerce's own section and your block are both rendering. That's expected: by default, Shaped Recommend leaves WooCommerce's sections alone.

To remove WooCommerce's version, go to Settings → General → WooCommerce Default Showcase and turn on Hide Related Products, Hide Up-sell Products or Hide Cross-sell Products.

Know what you're switching off. These hide WooCommerce's section on every page, unconditionally. If your own block is held back on some page (a condition, a limit, an empty pool), that page shows no section at all. Replacing Woo Slots covers this in more detail.

If the switch doesn't remove it, your theme is probably drawing that section from its own template rather than through WooCommerce.

The block lands in the wrong place on the page ​

Your theme has moved or removed some of WooCommerce's product-page output. This is common in heavily customised themes.

  1. Try a neighbouring position: Before tabs instead of After tabs, or After meta.
  2. If none of them land where you want, set Position On Page to Custom placement · Shortcode or Custom placement · Block and put it exactly where you want it. See Shortcode & Block.

The hook map lists the action and priority behind each position, if you want to compare it with your theme's template.

Nothing renders on a block theme ​

Block themes build their pages from blocks, so some of WooCommerce's classic PHP hooks never fire.

  • Cart positions render around WooCommerce's Cart block as well as the classic cart. Checkout positions Pro do the same around the Checkout block.
  • Product page and category positions depend on classic hooks. If your block theme's templates don't fire them, use the Shaped Recommend block in the Site Editor, on the relevant template.

That's why the block is in the free plugin: on a block theme it isn't a convenience, it's how you place a recommendation.

Analytics is empty on a store with traffic ​

Check that anything has rendered ​

A Recommendation that has never rendered shows zeros, and that's accurate. Confirm the blocks actually appear on the storefront first (above).

Check the scheduled jobs ​

Today's figures are calculated when you open the screen. Earlier days come from a nightly job that runs through WooCommerce's Action Scheduler. If your host has switched off WP-Cron (DISABLE_WP_CRON) without setting up a real server cron, events pile up but past days never get added up.

Look under WooCommerce → Status → Scheduled Actions for past-due sprcm_rollup_daily actions. Tools → Site Health also warns about a missed cron. Once the scheduler runs again, the next run catches up.

Check the date range ​

The free plugin shows up to the last 30 days. Older traffic needs a longer Pro Pro range.

Check permissions ​

A user who can manage Recommendations but has been explicitly denied sprcm_view_analytics sees figures withheld rather than zeroed. It looks like empty analytics, but it's a permissions issue.

Store Statistics isn't using my order data Pro ​

Until there's enough order history, a Recommendation set to Store Statistics falls back to rules. The builder says so: "Store Statistics needs order history, so until enough data builds up it falls back to category & popularity." Shoppers still see a normal block.

Check the state of the mined data:

bash
wp sprcm stats status

Then:

  1. Lower Minimum Co-Purchases. Try 5+ before you widen the Order History Window. A lower minimum responds faster and stays more current.
  2. Make sure there are paid orders in the window. Cancelled and refunded orders don't count.
  3. Check the scheduled jobs, the same way as for analytics. Mining runs in the background.
  4. Force a rebuild: wp sprcm stats rebuild --window=90d --keep. Use --keep on a live store, otherwise blocks fall back while the rebuild runs.

A setting won't save ​

"That setting needs full administrator permissions."

Three actions need the manage_options permission, which normally only Administrators have: Clean-up Data on Deletion, a Replace All import, and activating a Pro license. A Shop manager can build and run Recommendations but can't make store-wide destructive changes. The setting isn't saved, and the screen tells you so.

Import failed ​

  • "Could not read that file." The file couldn't be opened. Export again from the source store.
  • "That file is not a valid configuration file." It isn't a Shaped Recommend export, or it was edited by hand.
  • "That file was written by a newer version of the plugin. Update the plugin before importing it." Update this store first.
  • "“…” could not be imported because its settings are not valid." That one Recommendation was skipped. The Import report lists every skipped item.

Licenses are never exported or imported, so it's expected that the license is missing after an import.

Pro is active but Pro features are locked ​

  1. Is the free plugin active too? Pro is an add-on. Without Shaped Recommend it goes dormant, and its notice says "It needs the free Shaped Recommend plugin installed and active."
  2. Is the free plugin new enough? Pro checks the free plugin's version and tells you if it's too old. Update the free plugin.
  3. Look for a dormancy notice in wp-admin. It names exactly what's missing.

A lapsed license doesn't lock anything. Its notice says "Every feature keeps working — updates and support have stopped."

Products I don't want keep appearing ​

  • Out of stock? Add an In Stock filter set to Yes, or check WooCommerce's Hide out of stock items from the catalog setting.
  • Already in the cart? In automatic mode, a Cart recommendation already leaves out the cart's own products. With Choose Specific Filters, add Exclude Cart Items Pro.
  • Just bought? Add Exclude Purchased Pro. It's available on Thank You pages.
  • The same product every time? It may be pinned. Check Pinned Products in Step 1. Pins skip the filters by design.
  • Changes order on every visit? With no sorting rules, matching products come back in random order and are reshuffled on every page view. Add a sorting rule.

Still stuck ​

When you contact support, include your WordPress and WooCommerce versions, your theme, whether Pro is active, whether the builder's Live Preview shows products, and whether the block appears in a private window.