Store admin
Troubleshooting
Symptoms, causes and fixes for the problems store admins most often meet with the Companion plugin, from sign-in errors to late emails.
Find the symptom you are seeing, then follow the fix. Most problems come down to one of four things: the Storefront URL is not set, a setting is still within its 5-minute cache, a required plugin (Contact Form 7, Brevo) is missing, or WordPress’s scheduler is not running often enough. Problems with the storefront’s own deployment are covered in Storefront troubleshooting.
First checks
Section titled “First checks”- Is the Storefront URL set? Go to StoreFront → Settings → General and check Storefront URL. Emails, preview links, product redirects and wallet payments all depend on it.
- Did you press Save Changes? One button saves every tab. If any tab has a problem, nothing is saved; look for a red message at the top of the screen.
- Have 5 minutes passed? The storefront caches settings and page content for up to 5 minutes. Wait, then reload the storefront page (a hard reload, or a private window).
- Is the feature switched on? Several features are off by default: Compare, the shop-page banner, the promo popup, most home-page sections and the newsletter provider.
Sign-in and accounts
Section titled “Sign-in and accounts”| Symptom | Cause | Fix |
|---|---|---|
Nobody can sign in or register; the storefront reports a server error (jwt_secret_missing) |
The signing secret RSC_JWT_SECRET is not in wp-config.php. The Social Login tab shows an amber “JWT signing secret is not configured” banner. |
Copy the ready-made line from that banner (it includes a freshly generated secret) and ask whoever manages the server to add it to wp-config.php. See Sign-in and security. |
| New customers can’t sign in after registering | Email verification is required, and the verification email did not arrive. | Check email delivery and that the Email verification email is enabled. See Emails. |
| The Google or Facebook button is missing | Google needs a Client ID; Facebook needs both App ID and App Secret. | Fill them in under Authentication → Social Login and save. The badge shows Connected when ready. |
Google says Error 400: redirect_uri_mismatch |
The storefront’s login address is not listed in Google Cloud. | Add the storefront address followed by /login (no trailing slash, no language prefix) to Authorised redirect URIs. The setup guide on the Social Login tab shows the exact value. |
| Facebook sign-in works for you but not for shoppers | The Meta app is still in Development mode. | Switch the app to Live (it needs privacy-policy and data-deletion URLs). |
| An administrator can’t use Google or Facebook sign-in | Staff accounts are not allowed to use social sign-in, by design. | Sign in with the account’s password. |
| A shopper is asked for a password after choosing Facebook | Their Facebook email matches an existing account, which must be confirmed once. | Expected. They enter that account’s password once to link it. |
Social-login and Turnstile keys are set only in WordPress, never in the storefront’s configuration.
The settings screen
Section titled “The settings screen”| Symptom | Cause | Fix |
|---|---|---|
| StoreFront → Settings is blank, or the site shows a fatal error after installing from source | A copy taken straight from the code repository has not been built. | Install the release zip instead, or have a developer run the build (composer install and npm run build). See Install the Companion plugin. |
| Saving fails with “The Turnstile secret key is the same as the site key … nothing was saved.” | The site key was pasted into both fields. | Copy the secret key from your Turnstile widget in the Cloudflare dashboard into Secret Key, then save. |
| Saving fails with “Brevo is not ready yet …” or “Choose the Brevo form …” | The newsletter tab has Brevo on without a ready plugin or a chosen form. | Finish the Brevo steps on the Newsletter tab, or switch Brevo off, then save. |
| Saving fails with “… is not an image in the Media Library. Nothing was saved.” | An image field points at something that is not an image. | Choose an image from the Media Library again. |
| A field is greyed out with a “Defined in wp-config.php” chip | A setting is pinned in wp-config.php, which always wins. |
Change it in wp-config.php, or ask a developer to remove the constant. |
| A secret field is empty after saving | Saved secrets are never shown again, for security. | Expected. Leave it blank to keep the saved value, or type a new one to replace it. |
| The Header/Footer Scripts tab is read-only | Your account lacks the unfiltered_html permission. |
Ask a super admin or developer. See Scripts. |
| A number on the Compare tab jumps while you type | The field corrects itself on every keystroke. | Use the field’s arrows, or the keyboard’s arrow keys. |
| The header preview says “Set the Frontend URL in the Auth tab” | Older wording: the setting is now Storefront URL on the General tab. | Set the Storefront URL on the General tab. |
Changes not showing on the storefront
Section titled “Changes not showing on the storefront”| Symptom | Cause | Fix |
|---|---|---|
| A saved change hasn’t appeared | Settings and content are cached for up to 5 minutes. | Wait 5 minutes and reload. If you use the WP REST Cache plugin, it clears itself when products, reviews and settings change. |
| A home-page or shop banner button says “Shop Now” and goes to the shop, although you left it empty | Empty button text and links fall back to “Shop Now” and the shop page. | Type your own label and link, or remove the slide if you want no button. |
| A home-page section never shows, even when switched on | The storefront’s deployment can leave sections out entirely. | Ask your developer to check the HOME_SECTIONS setting. See Home page. |
| Compare buttons are missing | Compare is off by default. | Switch it on under Settings → Compare. |
| Guests’ wishlist hearts ask them to sign in | The storefront wishlist is for signed-in customers only. | Expected. |
| Today’s Deals is empty | No simple product has a scheduled sale ending today, or the WordPress timezone is wrong. | See Products. |
Emails and background jobs
Section titled “Emails and background jobs”| Symptom | Cause | Fix |
|---|---|---|
| Email buttons open a page of raw code (JSON) | No Storefront URL is set, so links fall back to WordPress’s API. | Set it under StoreFront → Settings → General. |
| Emails don’t arrive, or land in spam | The server’s basic mail function is blocked or untrusted. | Set up an SMTP or transactional-email plugin. |
| Back-in-stock emails arrive late | WordPress’s scheduler only runs when someone visits WordPress, which is rare on a headless store. | Set up a real cron job. |
| Customers get two back-in-stock emails | WooCommerce’s experimental back-in-stock feature is on as well. | Remove WOOCOMMERCE_BIS_ALPHA_ENABLED from wp-config.php. |
| Text in an email’s “Additional content” doesn’t appear | These six emails don’t print that field. | Ask a developer to override the email template instead. |
| Brand cards have no category badge | The daily brand job has not run yet. | Wait a day, or run it once with WP-CLI. |
Forms and bot protection
Section titled “Forms and bot protection”| Symptom | Cause | Fix |
|---|---|---|
| The Contact page shows a notice instead of a form | Contact Form 7 is not active, or no form is chosen. | Activate Contact Form 7 and choose a form under Pages → Contact. See Pages and content. |
| Every contact message fails | The chosen form requires a field the storefront doesn’t send. | Read the warning under Form on the Contact tab and fix the form. |
| No Turnstile check appears on forms | Turnstile is off store-wide, or a key is missing (“Turnstile isn’t active until both keys are saved”). | Switch it on and save both keys under Authentication → Turnstile. |
| Shoppers see “We could not verify you are human right now” | Cloudflare rejected the secret key, or could not be reached. The Turnstile card shows when it was rejected. | Paste the correct secret key and save. |
| The promo popup’s sign-ups don’t reach the newsletter | The popup’s email box isn’t connected yet. | Collect sign-ups with the footer newsletter form. See Scripts and promo popup. |
| The newsletter form says sign-up is unavailable | No newsletter provider is switched on. | Set up Brevo on the Newsletter tab. |
Pages, products and reviews
Section titled “Pages, products and reviews”| Symptom | Cause | Fix |
|---|---|---|
| A policy page shows “page not found”, and its footer link is gone | No published page is chosen for it. | Choose one under Pages → Static Pages. |
| A policy page or SEO setting is needed in another language | Extra languages are added by a developer (the rsc_storefront_page_languages filter). |
Ask your developer; there is no switch in wp-admin. |
| Preview or View opens the WordPress theme | No Storefront URL is set. | Set it on the General tab. |
| A product video vanished after saving | It failed a check, such as an upload without a poster image. | Read the notice shown after saving and fix the video. |
| No colour swatches | The attribute’s slug is not exactly color. |
Check under Products → Attributes. |
| Deleted reviews’ photos are still in the Media Library | Deleting a review may leave its files behind. | Before deleting a review, remove its files in the Review media & reports box. See Reviews. |
| Stock Notifications “Export CSV” contains more than the filtered list | The export always includes every sign-up. | Filter the spreadsheet afterwards. |
Admin notices you may see
Section titled “Admin notices you may see”These notices appear at the top of wp-admin for administrators. None of them switches anything off.
| Notice | What it means | What to do |
|---|---|---|
| “StoreFront: Stripe did not register the storefront domain …” | Stripe refused to register your storefront’s domain for wallet payments, so the Apple Pay and Google Pay buttons won’t appear. Card payments are not affected. | Check the reason Stripe gave and your Stripe keys. It is retried automatically within the hour, or straight away when the Storefront URL or Stripe keys change. Local and test addresses are never sent. Keep Link switched off in the Stripe plugin: only Apple Pay and Google Pay are supported on the storefront. See Payments. |
| “StoreFront: (plugin and version) is active, but storefront payments are verified against …” | Your WooCommerce Stripe Gateway or WooCommerce PayPal Payments version is outside the range the storefront was tested with. Payments keep working. | Test a sandbox payment before relying on this version, or ask your developer to confirm it. |
| “StoreFront: this store takes payments on the storefront, but RSC_STOREFRONT_SHARED_SECRET is not defined …” | A shared secret between WordPress and the storefront is missing, so checkout attempts are not limited per shopper. | Ask your developer to set the same secret in wp-config.php and in the storefront’s configuration. |
| “(Yoast SEO or Rank Math) is now where SEO is edited for the storefront. Run “Sync SEO” once …” | You activated or switched SEO plugins. | Click Open the SEO settings and run Sync SEO. See SEO. |
| “StoreFront: WooCommerce’s built-in customer stock notifications … are switched on alongside …” | Two back-in-stock systems are on, so customers may be emailed twice. | Remove WOOCOMMERCE_BIS_ALPHA_ENABLED from wp-config.php. |
Still stuck?
Section titled “Still stuck?”Gather the details your developer will need: what you did, what you expected, what happened, the time, and a screenshot of any message. Check WooCommerce → Status → Scheduled Actions for failed actions and WooCommerce → Status → Logs for errors.
WooCommerceStatusLogsNext steps
Section titled “Next steps”Storefront troubleshootingProblems with the storefront deployment itself.
Connect the storefrontSet the Storefront URL and check the connection.
Emails and background jobsEmail delivery and real cron jobs.
FAQShort answers to common questions.
Storefront Playbook · Built by weLabsFeaturesFAQTalk to us