Skip to main content

Troubleshooting & FAQ

Common issues and solutions for the Flavor Starter Theme and WP eCommerce Core Plugin.

Installation & Setup​

License activation fails​

  • Verify your license key is correct and includes dashes (format: FLVR-XXXX-XXXX-XXXX-XXXX)
  • Ensure your server can reach license.flavorteam.dev over HTTPS (check firewall/curl restrictions)
  • Check that the sodium PHP extension is installed (php -m | grep sodium)
  • If on shared hosting, ask your provider to whitelist outbound HTTPS to license.flavorteam.dev

Maximum activations reached​

Each license tier has a domain limit. To free up a slot:

  1. Go to your Flavor Hub Portal
  2. Deactivate an existing domain
  3. Re-activate on the new domain
tip

Staging/development subdomains (e.g., staging.example.com, dev.example.com) do not count toward your domain limit.

Plugin fails to create database tables​

  • Ensure your MySQL user has CREATE TABLE privileges
  • Check that wp-config.php has the correct database credentials
  • Try deactivating and reactivating the plugin
  • Check the WordPress debug log (wp-content/debug.log) for specific SQL errors

"Flavor theme requires WP eCommerce Core plugin"​

The theme depends on the plugin. Install and activate the plugin first, then activate the theme.

"Core components are not installed"​

After a fresh install or theme update, the theme needs to download its core components from the license server:

  1. Go to the main Flavor page (click Flavor in the WordPress admin sidebar)
  2. Verify your license is active
  3. Click "Check for Updates" to trigger component download
  4. Ensure your server has write permissions on wp-content/themes/flavor-starter/

Fingerprint verification failed — premium features locked​

The Ed25519 license fingerprint file is missing or corrupt:

  1. Go to the main Flavor page
  2. Click Deactivate, then Activate again
  3. If the issue persists, check file permissions on wp-content/ (must be writable by PHP)

URLs, Permalinks & Routing​

Product pages show 404 after activation​

WordPress rewrite rules need to be flushed after theme/plugin activation:

  1. Go to Settings → Permalinks
  2. Click Save Changes (no need to change anything)
  3. If the issue persists, add ?wpec_flush_rules to any admin URL (e.g., yoursite.com/wp-admin/?wpec_flush_rules)

Shop/category URLs not working​

Same solution as above — flush permalinks. If category URLs still don't work:

  • Verify the category has a valid slug (no special characters)
  • Check that the shop page is assigned in Flavor Options → Shop

Shop search returns wrong results​

WordPress reserves the ?s= URL parameter for its built-in search. The storefront uses ?q= instead. If you're building custom search links, use ?q= not ?s=.

Menu & Navigation​

Saving menu returns "Not Acceptable" (406) or "Forbidden" (403)​

This is caused by ModSecurity (WAF) on your hosting blocking the menu save request because it contains too many form fields. Each menu item sends ~12 POST parameters, so 80+ items exceed the default limit of 1000.

Solution (choose one):

Option A — cPanel: Go to cPanel → ModSecurity → Disable rule #400000 for your domain

Option B — modsec2.user.conf (if your host supports it):

SecArgumentsLimit 3000
SecRequestBodyNoFilesLimit 1048576
SecRuleRemoveById 400000

Option C — Contact your host: Ask them to increase SecArgumentsLimit to 3000 for your domain.

note

This is a WordPress core limitation, not specific to our products. Any WordPress site with 80+ menu items can trigger this.

Mobile menu broken after enabling Mega Menu​

Mega Menu CSS can override mobile menu positioning. If your mobile menu is misaligned:

  1. Check that your header template uses position: static on the nav container (not relative)
  2. If using a custom CSS, add !important to mobile menu positioning rules
  3. Test with Mega Menu disabled to confirm it's the cause

Payment Gateways​

Payment failed during checkout​

General troubleshooting steps:

  1. Check the order note in eCommerce → Orders for the specific error message
  2. Verify your payment gateway API credentials are correct (test/live mode)
  3. Ensure your server can make outbound HTTPS connections
  4. Check that the callback/webhook URL is accessible (not blocked by firewall or .htaccess)
  5. Try a test payment with a different card/method

Viva Wallet payment errors​

  • Verify your Merchant ID and API Key in eCommerce → Settings → Payments
  • Ensure you're using the correct environment (demo vs production)
  • Check that the Source Code is created and linked correctly in Viva's dashboard
  • The callback URL must be publicly accessible (no basic auth, no IP restrictions)

Stripe payment not completing​

  • Check that your Stripe webhook is configured and the signing secret matches
  • Verify you're using the correct API keys (test vs live)
  • Check the Stripe Dashboard → Developers → Logs for detailed error information
  • Ensure 3D Secure is handled (our integration supports it automatically)

Greek bank payments (IRIS/Eurobank/NBG)​

  • These gateways require specific IP whitelisting — contact your bank for details
  • Test transactions must use the bank's sandbox environment
  • Some banks require a separate callback URL per payment method

Email & Notifications​

Emails are not being sent​

  1. Go to Flavor Options → Modules → SMTP Mailer and verify your settings
  2. Send a test email from the SMTP settings page
  3. Check your spam/junk folder
  4. If using Brevo (Sendinblue), verify your API key and sender email is verified
  5. Enable WP_DEBUG to see SMTP error logs

PDF invoice email not sending or missing attachment​

  • Check that the PDF module is active (Flavor Options → Modules → PDF Invoices)
  • Verify your server has write permissions on the temp directory
  • If using Brevo, PDF attachments are sent via the Brevo API (not PHPMailer) — check API logs

Contact form spam protection not working​

  • Verify your reCAPTCHA or Turnstile keys are correct (site key + secret key)
  • The site key goes in Flavor Options → Modules → Contact Form
  • Test in an incognito window (browser extensions can block captcha)

Theme & Page Builder​

Page Builder blocks not rendering​

  • Clear any caching (a caching plugin, your server's object/page cache, or your CDN), then reload the page.
  • Make sure the Flavor Starter Theme is up to date from the main Flavor page.
  • Open the page in the builder and click Update to re-save it.

Images look wrong after changing size settings​

When image size settings change, existing thumbnails aren't regenerated automatically:

  1. Install a "Regenerate Thumbnails" plugin
  2. Run the regeneration process
  3. Clear your CDN/browser cache

Cart & Checkout​

Cart appears empty after page refresh​

  • Check that cookies are enabled in the browser
  • Verify no caching plugin is caching the cart page (cart pages should be excluded from cache)
  • If using Cloudflare or CDN, exclude /wp-json/ec/v1/cart* from caching

Non-logged-in users cannot access checkout​

  • Check eCommerce → Settings → Checkout — "Allow guest checkout" must be enabled
  • Verify the checkout page template is assigned correctly

Security & Access​

Locked out after too many login attempts​

The built-in brute force protection locks accounts after repeated failures:

  • Wait 15 minutes for the lockout to expire
  • Or add ?flavor_unblock=1 to the login URL to clear the lockout

REST API returns 401/403 errors​

  • Check Flavor Options → Optimize → REST API — it may be restricted to logged-in users
  • If disabled for non-authenticated users, your storefront React app won't work
  • Ensure the ec/v1 and flavor/v1 namespaces are in the allowed list

Hosting security quarantined files​

Some hosting security scanners (Imunify360, ClamAV, ModSecurity) may flag ionCube-encoded files. These are legitimate encoded files used for license protection.

  • Contact your host and ask them to whitelist the flagged files
  • Do NOT use obfuscated PHP — we use ionCube encoding specifically because it's recognized by hosting providers

Performance​

Website crashed with "508 Resource Limit Reached"​

This usually indicates an infinite loop in JavaScript (React re-renders):

  1. Disable the React storefront temporarily (add ?flavor_no_react=1 to the URL)
  2. Check the browser console for rapid repeated API calls
  3. If a recent code change caused it, revert and rebuild

How do I reduce admin page load time?​

Go to Flavor Options → Optimize and disable unnecessary Block Editor (Gutenberg) scripts if you don't use the block editor.

ERP & Invoicing​

myDATA invoice transmission fails​

  • Verify your AADE credentials in eCommerce → ERP → Invoicing → myDATA Settings
  • Test in sandbox mode first before switching to production
  • Check that your server can reach the AADE API endpoints
  • Review the transmission log for specific error codes

PDF invoices not generating​

The PDF engine tries multiple methods in order: dompdf → wkhtmltopdf → HTML fallback

  • Check that dompdf composer package is installed
  • If fonts are missing, ensure the fonts/ directory is writable
  • Check the WordPress debug log for specific dompdf errors

Updates & Licensing​

Update not showing on the dashboard​

  • Verify the Flavor Core Plugin is installed and activated
  • Go to the main Flavor page and click "Check for Updates"
  • Verify your license is active and the domain is authorized
  • Updates require an active subscription — expired licenses don't receive updates

All modules locked after license expiry​

When a license expires, premium modules are locked but your core store keeps running:

  • If you need a little time before renewing, you can turn on the grace period to keep premium features working temporarily — see Can I keep premium features working after my license expires? below.
  • Renew your license from the Flavor Hub Portal.
  • After renewal, modules unlock again on the next automatic license check (within ~12 hours) — or right away if you click Check for Updates on the main Flavor page.

Can I keep premium features working after my license expires?​

Yes — Flavor includes an opt-in grace period for exactly this situation (for example, a renewal that hasn't gone through yet). It is not turned on automatically; you switch it on when you need it:

  1. As expiry approaches — and again once a license has expired — a banner appears in your WordPress admin (on the main Flavor page and as a notice across the admin area). You can dismiss the notice; it reappears daily until the license is renewed or the grace period ends.
  2. Click Activate grace period on the banner. Your premium features keep working for a limited number of days.
  3. The exact length is shown on the banner ("…for N more days"). It's set on your license and is typically around two weeks.
  4. One activation covers both the theme and the plugin.
  5. While grace is active, the banner shows the days remaining and a renew link. You can switch it off again with Deactivate grace.

When the grace period ends — or if you never turn it on — premium features lock until you renew. A license that has been suspended or revoked cannot use the grace period.

note

The grace period covers a lapsed subscription. It is unrelated to the license server being temporarily unreachable — that's handled separately (see the next question).

Does the store stop working if the license server is down?​

No. License checks are cached and refreshed automatically about every 12 hours. If our server is briefly unreachable, your store keeps working normally on the last successful check — premium features stay unlocked and nothing is disrupted. Verification resumes on its own once the connection is restored.

Your store only needs to reach the server occasionally, so it tolerates an extended outage (roughly a month) before the license falls back to an unverified state.

note

This is different from the grace period, which is about your subscription expiring — not about connectivity.

How do I roll back to a previous version?​

  1. Download the previous version ZIP from your portal
  2. Deactivate the current theme/plugin
  3. Delete it from WordPress
  4. Upload and activate the previous version
  5. Contact support if you need help

Still Need Help?​

If you didn't find the answer to your problem here:

  1. Check the full documentation for detailed guides
  2. Search existing issues in our Bug Tracker — someone may have reported the same problem
  3. Submit a support ticket through your Flavor Hub Portal
  4. Report a bug directly in our Bug Tracker
tip

When reporting an issue, include: your WordPress version, PHP version, theme/plugin version, the exact error message, and steps to reproduce the problem. This helps us resolve it faster.

Last updated on