ProRank SEO

Troubleshooting

Symptoms and fixes for the things that go wrong most often with the ProRank Shopify app.

The single most common issue is "schema is saved in the app but not visible on the storefront". It is almost always a disabled or stale theme app embed. Start there.

Schema not rendering despite being saved

Symptom: Schemas show as saved in the Schema tool, but they don't appear in the storefront page <head>. Live Schema Validation reports "Missing" for every template.

Cause: The ProRank Schema JSON-LD theme app embed is disabled on the active theme, or its UUID has gone stale after an app version update.

Fix — cycle the embed:

Online Store → Themes
  → Customize (on the active / live theme)
    → App embeds
      → ProRank Schema JSON-LD
      → Toggle OFF → Save
      → Toggle ON  → Save

After the cycle, re-run Live Schema Validation. All rows should report green within a minute or two (account for Shopify's edge cache).

See also Schema.

Theme SEO Controls action returns "RequestGrantUserError: optional scopes subset of []"

Symptom: Clicking any Theme SEO Controls action (image-ref swap, collection noindex, customer auth cleanup) fails with the literal error RequestGrantUserError: optional scopes subset of [].

Cause: The write_themes optional scope has not been granted or is not available to this app version. Either:

  • The app has not received Shopify's protected-scope exemption for theme file writes, OR
  • The app owner has not released an app version that exposes the optional scope, OR
  • The merchant has not approved the grant in the app.

Fix: Open Visibility → Theme SEO → Grant theme write accessinside the app and approve the optional-scope request. If that button reports "optional scope not available" or Shopify denies themeFilesUpsert, the app-owner side needs Shopify approval/release before that action can run.

See also Theme SEO Controls.

IndexNow verification key returns 404

Symptom: Opening https://your-shop.com/apps/prorank/<key>.txt returns 404, or IndexNow submissions all fail with a key-verification error.

Cause: The Shopify app proxy route is not reachable for this install, the root verification redirect was not created, or a custom firewall / Cloudflare layer is challenging the request.

Fix:

  1. In ProRank, open IndexNow → Settings and confirm app proxy status. The UI shows a live status check against the key URL.
  2. Confirm the root verification URL redirects to /apps/prorank/<key>.txtand that the proxy URL returns the key as plain text. If the proxy route itself is missing, contact support; it is configured at the app level.
  3. If you use Cloudflare or a custom WAF in front of the store, allow /apps/prorank/* through without challenges.

Image Optimize & Replace — verification failed

Symptom: An Optimize & Replace row reports "verification failed". The product media looks correct in the Shopify admin, but the live storefront still shows the old / oversized image.

Cause: The theme template references an old copy of the image in the Files library (file id A), while the product media is now optimised but stored under a different id (file id B). The Optimize & Replace flow only touches product media — it does not rewrite theme references.

Fix: Use Theme SEO Controls → image reference swap to rewrite the theme template's reference. This requires the optional write_themes scope and Shopify protected-scope approval; see the scope-grant section above.

You can also avoid this by optimising the file in place in the Files library (Images → Store Files tab). That keeps the same file id and the theme reference continues to resolve.

Live Schema Validation shows "Missing" for every template type

Symptom: Every template row (product, collection, page, article, home, blog index) reports "Missing" or "No JSON-LD found" even after saving schemas in the Schema tool.

Cause: The theme app embed is off, or stale (post-update UUID change). This is the same root cause as the first section, just observed via the validator.

Fix: Cycle the ProRank Schema JSON-LD app embed (toggle OFF → Save → toggle ON → Save) on the active theme. Re-run Live Schema Validation. All rows should turn green within a minute.

Customer auth redirect cleanup didn't drop the crawler row

Symptom: The crawler audit still reports a customer auth redirect on a non-auth URL, even though you ran the Theme SEO Controls customer auth redirect cleanup action.

Two common causes:

  • The action did not actually run. If write_themeswasn't granted at the moment you clicked Apply, the call would have returned the scope error — and the action would be queued or marked "needs scope", not "Applied". Open the Theme SEO Controls activity log and confirm the row shows Applied, not Pending.
  • Crawler cache. Third-party crawlers (Ahrefs, Semrush, GSC URL inspection) cache recently-seen URLs. Re-run the crawler / inspection after a fresh fetch.

Fix: Confirm the action is Applied in the activity log, then either re-trigger the third-party crawl or wait one re-crawl cycle. If the action shows Pending, grant write_themes first and re-apply.

Bulk save / bulk Optimize & Replace blocked with an upgrade prompt

Symptom: Clicking a bulk action returns "quota reached" or shows an upgrade prompt before the action runs.

Cause: The BillingGuard for the current plan's usage cycle has been hit. Bulk operations and IndexNow submissions are quota-counted; per-row edits are not.

Fix: Wait for the next cycle (date shown in the dashboard), upgrade the plan, or split the work across cycles. See Billing & Trial.

Audit results look stale or didn't update after fixes

Symptom: You fixed a batch of issues, but the dashboard still shows the old counts.

Cause: The next scheduled audit hasn't run yet.

Fix: Click Run audit on the dashboard to force an immediate re-scan. This counts against the plan's audit cycle quota.

Quick reference — where to start

Schema problems

Cycle the theme app embed first, then re-run Live Schema Validation.

Theme write problems

Check the scope grant in Visibility → Theme SEO.

IndexNow problems

Check the root key URL, redirect, and app proxy response.

Image still oversized on storefront

Use Theme SEO Controls image-ref swap, or optimise in-place in the Files library.

Want to undo a theme edit

Use the per-action Rollback button in Theme SEO Controls, or restore from your own theme backup/version history if available.

Anything else

Contact support with the shop URL and a screenshot.