Troubleshooting

Find the symptom, check the cause, apply the fix. Problems inside wp-admin, such as settings that will not save, are covered in Store admin troubleshooting.

Tip

When something fails in WooCommerce mode, switch to Demo Mode (COMMERCE_SOURCE=mock) and try again. If Demo Mode works, the problem is in the connection to WordPress, not in the storefront.

Install and local runs

Symptom	Cause	Fix
Install or build fails with syntax errors, or pnpm complains about the engine	Node is older than 22, often an old Node earlier on your PATH	Run node --version. Install Node 22 or newer and put it first on your PATH.
pnpm is missing or the wrong version	Corepack is not enabled	Run corepack enable, then pnpm install again. Do not use npm or Yarn.
Unknown COMMERCE_SOURCE: …	A typo in COMMERCE_SOURCE	Use woocommerce, or leave it unset (or mock, fake) for Demo Mode.
Auth.js error MissingSecret	AUTH_SECRET is not set	Generate one with openssl rand -base64 32 and add it to apps/storefront/.env.
A page shows “Compiling /route …” forever, or e2e tests time out on page loads	A stuck Turbopack development cache	Stop the dev server, run rm -rf apps/storefront/.next/dev, and start again.
The page renders from a phone or tunnel, but no button works	Next.js blocks dev scripts for hosts other than localhost	Add the host to DEV_ALLOWED_ORIGINS and restart. See Install.
pnpm test:e2e cannot find a browser	Playwright’s Chromium is not installed	Run pnpm --filter @welabs/retail-storefront exec playwright install chromium.
e2e tests fail oddly while pnpm dev is running	The suite starts its own Demo Mode dev server, which clashes with yours	Stop pnpm dev before pnpm test:e2e.
Changes to .env have no effect	The dev server reads .env at start	Restart pnpm dev. For NEXT_PUBLIC_ variables in a build, rebuild.

Connecting to WordPress

Symptom	Cause	Fix
The storefront still shows the demo catalogue	COMMERCE_SOURCE is not woocommerce, or a shell variable overrides the file	Set COMMERCE_SOURCE=woocommerce in apps/storefront/.env and restart.
Error: WOO_STORE_URL is not set	WooCommerce mode without a store address	Set WOO_STORE_URL to the WordPress site, with no trailing slash.
TLS or certificate errors against a .test site	Node does not trust the local development certificate	Set NODE_EXTRA_CA_CERTS to your local CA in the shell, or WOO_INSECURE_TLS=1 in development only. See Install.
Every page returns 500 and the log shows connection timeouts	The WordPress host, or a CDN in front of it, is slow to accept connections	Check that WordPress answers at WOO_STORE_URL. On a Node host, raise WOO_CONNECT_TIMEOUT_MS.
Sign-in and registration fail; WordPress answers jwt_secret_missing	RSC_JWT_SECRET is missing from wp-config.php	Add it. The Companion’s Social Login tab shows a ready-to-paste line.
Sign-in fails with “verify your email”	The account’s email address is not verified, often because WordPress cannot send mail	Set up SMTP in WordPress, then use the resend link. Never disable verification in production.
Verification or reset emails open raw JSON	The Storefront URL is not set in WordPress	Set StoreFront → Settings → General → Storefront URL.
Newsletter sign-up, contact form, profile photo or compare sync fail; sign-in works	RSC_API_URL is unset, so these use a development fallback address	Set RSC_API_URL to https://your-wordpress/wp-json/retail-store-companion/v1.
Checkout lists every country, not just yours	WooCommerce REST keys are missing or rejected	Set WOO_CONSUMER_KEY and WOO_CONSUMER_SECRET. See Connect WooCommerce.
A change in WordPress does not show on the storefront	Settings and content responses are cached for about 5 minutes	Wait five minutes and reload. No redeploy is needed.
The /brands page shows no categories for brands	The daily brand job has not run yet	Run wp cron event run rsc_backfill_brand_primary_category.
WordPress shows a notice about a missing shared secret	RSC_STOREFRONT_SHARED_SECRET is not defined	Add it to wp-config.php with the same value as STOREFRONT_SHARED_SECRET.

Payments and sign-in providers

Symptom	Cause	Fix
An enabled payment method does not appear at checkout	The storefront only offers gateways it can take payment through on its own checkout page	Use Stripe, PayPal or the offline methods. The server log names any gateway it skipped. See Payments.
Payment form still in test mode after going live	The gateway’s mode is set in WordPress	Switch the gateway to live in WooCommerce → Settings → Payments. The next checkout uses it; no redeploy.
No Apple Pay or Google Pay button	Wallets need HTTPS, a domain registered with Stripe, and the wallet switched on for that page in the Stripe plugin	Check all three. Local and test hosts are never registered with Stripe. On a variable product, the button waits until every option is chosen.
No express button on product pages, but cart and checkout have one	WooCommerce REST keys are missing	Set the REST keys.
The Google or Facebook button is missing	The provider is not configured in WordPress; the storefront shows only configured providers	Add the credentials under StoreFront → Settings → Authentication → Social Login.
Google sign-in fails with a redirect error	The OAuth client’s redirect URI does not match	Set the authorised redirect URI to the storefront’s /login address, exactly.

Deployment

Symptom	Cause	Fix
Build warns that the middleware file convention is deprecated	Expected: OpenNext supports only Edge middleware	Ignore it. Do not rename middleware.ts.
Pages have no canonical address, sharing tags or language links	SITE_URL is unset or invalid in production	Set SITE_URL to the public address, such as https://shop.example.com.
Sign-in redirects to localhost or an internal address	Auth.js does not see the public host behind the proxy	Set AUTH_TRUST_HOST=true.
Cloudflare deploy went to a different Worker	The name in wrangler.jsonc does not match the Workers Builds project	Make both names the same.
Cloudflare variables vanished after a deploy	keep_vars was removed from wrangler.jsonc	Restore "keep_vars": true and set the variables again in the dashboard.
A NEXT_PUBLIC_ change has no effect	These values are compiled in at build time	Make the value available to the build and rebuild.
Pages fail with a Template Family error	STOREFRONT_TEMPLATE_FAMILY names a family that does not exist	Use default, or remove the variable.
The language switcher is missing	Only one valid Locale is configured	Check STOREFRONT_LOCALES, for example en,ar. Invalid entries are dropped silently.

Still stuck

Collect the server log lines around the failure, the storefront’s environment variable names (never their secret values), and the Companion plugin’s version, then contact your weLabs contact.

Next steps

Store admin troubleshootingProblems inside wp-admin.

Environment variablesEvery variable and its default.

FAQCommon questions from clients and teams.