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 Flavor → Dashboard in the WordPress admin
  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 Flavor → Dashboard
  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​

  • Ensure the React app is built: the flavor-starter/react-app/dist/ folder must exist
  • If you modified any JSX files, rebuild: run npm run build in the react-app/ folder
  • Clear any server-side caching (object cache, page cache)

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 reset (requires server file access)
  • Or remove the lockout from the database: delete the relevant row from the flavor_options table

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 Flavor → Dashboard 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 the core functionality continues:

  • Renew your license from the Flavor Hub Portal
  • After renewal, modules unlock automatically (within 12 hours or on next page load)

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

No. The license system includes a 14-day grace period. If the server is temporarily unreachable, your store continues working normally. License verification resumes automatically when connectivity is restored.

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