Skip to content
SpecCart Docs

Troubleshooting

This guide helps you diagnose and resolve common SpecCart issues. Steps are written for store owners without requiring technical knowledge.

Configurator Issues

Section titled “Configurator Issues”

Configurator Not Appearing on Product Page

Section titled “Configurator Not Appearing on Product Page”

Symptoms:

  • Product page displays normally but no configurator appears
  • No “Configure Lenses” button visible
  • Product displays like a regular WooCommerce product

What to Check:

  1. Product-level setting:

    • Go to Products → All Products
    • Edit the product
    • Scroll to the SpecCart Lens Configuration panel
    • Verify “Enable lens customization for this product” is checked
    • Click Update to save

  2. Global setting:

    • Go to SpecCart > Settings → General
    • Verify the configurator is enabled globally
    • Save changes if you made any modifications

  3. Product type:

    • In the product editor, check the Product Data panel
    • SpecCart works with Simple and Variable products
    • If the product is marked as Virtual only or Downloadable only, the configurator won’t appear

  4. Browser cache:

    • Clear your browser cache (Ctrl+Shift+Delete or Cmd+Shift+Delete)
    • Try viewing the product in an incognito/private window
    • Try a different browser

  5. Site cache:

    • If you use a caching plugin (WP Rocket, W3 Total Cache, etc.), clear the cache
    • If you use a CDN (Cloudflare, etc.), clear the CDN cache

When to Contact Your Developer:

If you’ve checked all the above and the configurator still doesn’t appear, contact your developer. The issue may be:

  • JavaScript conflicts with your theme or another plugin
  • Theme template modifications
  • Server configuration issues

Configurator Shows Error Message

Section titled “Configurator Shows Error Message”

Symptoms:

  • Configurator appears but shows “Failed to load configuration”
  • Error message appears when trying to use the configurator
  • Configurator is blank or partially loaded

What to Check:

  1. Check your browser console:

    • Press F12 on your keyboard
    • Click the Console tab
    • Look for red error messages
    • Take a screenshot of any errors

  2. Clear permalinks:

    • Go to Settings → Permalinks
    • Don’t change anything, just click Save Changes
    • This refreshes WordPress URL routing
    • Return to the product page and test again

  3. Log out and back in:

    • If you’re logged into WordPress, try logging out
    • Clear your browser cookies
    • Log back in and test again

  4. Test as a customer:

    • Open the product page in an incognito/private window (not logged in)
    • See if the configurator loads for non-logged-in visitors

When to Contact Your Developer:

If errors persist, provide your developer with:

  • Screenshots of browser console errors
  • The exact error message shown to customers
  • What you’ve already tried from the steps above

Prices Not Calculating Correctly

Section titled “Prices Not Calculating Correctly”

Symptoms:

  • Total price is incorrect
  • Lens upgrade prices aren’t added
  • Price changes don’t reflect when options are selected

What to Check:

  1. Verify pricing settings:

    • Go to SpecCart > Settings
    • Check the Lens Usage, Packages, and Add-Ons tabs
    • Verify all options have prices set
    • Make sure price fields aren’t empty or set to zero (unless free)

  2. Check base product price:

    • Edit the product
    • In the Product Data panel, verify the product has a Regular price
    • The configurator adds to this base price

  3. Per-product pricing:

    • If you’ve enabled “Use custom pricing for this product”, verify those prices are set correctly
    • Per-product pricing overrides global pricing completely

  4. Clear cache and test:

    • Clear your site cache
    • Clear your browser cache
    • Add the product to cart and verify the cart total

When to Contact Your Developer:

If prices are still incorrect after checking settings and clearing cache, contact your developer. The issue may be:

  • Conflicting pricing plugins (dynamic pricing, sale price overrides)
  • Custom code modifying WooCommerce prices
  • Database caching issues

Admin Panel Issues

Section titled “Admin Panel Issues”

Settings Not Saving

Section titled “Settings Not Saving”

Symptoms:

  • Click “Save” but settings don’t persist
  • Page refreshes but shows old values
  • No success message appears

What to Check:

  1. Look for error messages:

    • Check the top of the settings page for red error boxes
    • Note any error messages displayed

  2. Check browser console:

    • Press F12
    • Click the Console tab
    • Look for red error messages when you click Save
    • Take a screenshot of errors

  3. Try a different browser:

    • Test in Chrome, Firefox, or Safari
    • Sometimes browser extensions interfere with admin panels

  4. Check your user role:

    • Go to Users → Profile
    • Verify your role is Administrator or Shop Manager
    • Only these roles can manage SpecCart settings

  5. Disable other plugins temporarily:

    • Go to Plugins → Installed Plugins
    • Deactivate all plugins except WooCommerce and SpecCart
    • Test if settings save now
    • If they do, reactivate plugins one-by-one to find the conflict

When to Contact Your Developer:

If settings still won’t save, contact your developer with:

  • Screenshots of any error messages
  • Which browser you’re using
  • Whether it works after disabling other plugins

Prescription Uploads Not Working

Section titled “Prescription Uploads Not Working”

Symptoms:

  • Customers report they can’t upload prescription files
  • Upload button doesn’t work
  • Files upload but don’t appear in the order

What to Check:

  1. File size limit:

    • Go to Media → Add New in WordPress admin
    • Check the “Maximum upload file size” shown on that page
    • SpecCart requires at least 5MB for prescription uploads
    • If the limit is too low, contact your hosting provider to increase it

  2. File permissions:

    • Prescription files are stored in your WordPress uploads directory
    • Contact your hosting provider to verify file permissions are correct

  3. Check upload folder:

    • Go to Settings → Media
    • Verify the uploads folder path is correct
    • WordPress default is wp-content/uploads

  4. Test with a small file:

    • Try uploading a very small image (under 1MB)
    • If small files work but large files don’t, the issue is file size limits

When to Contact Your Developer/Host:

Prescription upload issues usually require:

  • Your hosting provider - For file size limits, file permissions, or server configuration
  • Your developer - For WordPress configuration or custom server setups

Order Prescription Data Missing

Section titled “Order Prescription Data Missing”

Symptoms:

  • Order exists but prescription information isn’t shown
  • Lens configuration missing from order details
  • Can’t verify prescription because data isn’t there

What to Check:

  1. Check the order status:

    • Go to WooCommerce → Orders
    • Open the order
    • Look for the SpecCart Lens Configuration panel on the right side

  2. Verify customer completed checkout:

    • Some customers abandon checkout before submitting payment
    • Check if the order status is Pending Payment or Failed

  3. Check if customer selected “Send Later”:

    • Look for the Prescription Upload Status section
    • If it shows “Pending Upload”, the customer chose to send their prescription later
    • They should have received an email with an upload link

  4. Review cart at time of order:

    • Check if the product was actually configured with lenses
    • Some customers might add the base product without configuring lenses

When to Contact Your Developer:

If prescription data is genuinely missing from completed orders, contact your developer. This could indicate:

  • Database issues
  • Cart data not saving properly
  • Theme or plugin conflicts affecting checkout

Email Issues

Section titled “Email Issues”

Prescription Emails Not Sending

Section titled “Prescription Emails Not Sending”

Symptoms:

  • Customers report they didn’t receive prescription upload links
  • Reminder emails aren’t being sent
  • Verification emails aren’t arriving

What to Check:

  1. Test general WooCommerce emails:

    • Place a test order
    • Verify you receive the standard WooCommerce order confirmation email
    • If general emails don’t work, the issue isn’t specific to SpecCart

  2. Check spam folders:

    • Ask customers to check spam/junk folders
    • Check your own spam folder for test emails

  3. Verify email settings:

    • Go to WooCommerce → Settings → Emails
    • Check that relevant emails are enabled
    • Verify the “From” email address is valid

  4. Check automation settings:

    • Go to SpecCart > Settings → Prescription
    • Verify “Send reminder emails” is enabled (if you want reminders)
    • Check the reminder schedule is configured

When to Contact Your Developer/Host:

Email issues often require:

  • Your hosting provider - To configure server email (SMTP)
  • Your developer - To install and configure an SMTP plugin
  • Email service provider - To set up professional email delivery

Email Content Not Displaying Correctly

Section titled “Email Content Not Displaying Correctly”

Symptoms:

  • Emails arrive but look broken
  • Prescription data is missing from emails
  • Formatting is wrong

What to Check:

  1. Test in different email clients:

    • Check the email in webmail (Gmail, Outlook.com)
    • Check in desktop email clients
    • Some email clients render HTML differently

  2. Check WooCommerce email settings:

    • Go to WooCommerce → Settings → Emails
    • Click on individual email types
    • Preview the email using the preview button

  3. Verify template customizations:

    • If your theme customizes WooCommerce email templates, it may need updates
    • Test with email customization plugins disabled

When to Contact Your Developer:

Email formatting issues usually require developer assistance, especially if your theme or another plugin customizes email templates.

Performance Issues

Section titled “Performance Issues”

Configurator Loads Slowly

Section titled “Configurator Loads Slowly”

Symptoms:

  • Configurator takes several seconds to appear
  • Product page is slow to load
  • Customers report performance issues

What to Check:

  1. Product image sizes:

    • Large product images slow page loading
    • Optimize images before uploading (use tools like TinyPNG or ShortPixel)
    • Recommended: Product images under 500KB

  2. Hosting resources:

    • Contact your hosting provider to verify you’re not hitting resource limits
    • Shared hosting plans may be too limited for busy stores
    • Verify you meet the requirements

  3. Caching configuration:

    • Enable page caching if not already enabled
    • Configure your caching plugin to cache WooCommerce pages
    • Use a CDN (Cloudflare, etc.) for static assets

  4. Plugin conflicts:

    • Temporarily disable plugins unrelated to WooCommerce
    • Look for plugins that add scripts to every page
    • Analytics plugins and chat widgets can slow page load

  5. Theme performance:

    • Test with a default WordPress theme
    • Some themes load excessive resources

When to Contact Your Developer/Host:

  • Hosting provider - For resource limits, caching, CDN setup
  • Developer - For code optimization, database optimization, advanced performance tuning

Admin Panel Slow or Times Out

Section titled “Admin Panel Slow or Times Out”

Symptoms:

  • SpecCart settings page loads very slowly
  • Timeout errors when saving settings
  • WordPress admin generally slow

What to Check:

  1. Increase PHP memory limit:

    • Contact your hosting provider to increase PHP memory to 256MB
    • Most hosts can do this through their control panel or support ticket

  2. Reduce number of products:

    • If you have thousands of products, some admin operations will be slower
    • This is a limitation of WordPress/WooCommerce, not specific to SpecCart

  3. Optimize database:

    • Ask your hosting provider or developer to optimize the WordPress database
    • Regular database maintenance improves performance

  4. Check for other admin slowness:

    • Test other admin pages (Products, Orders, Settings)
    • If all admin pages are slow, it’s a general hosting/WordPress issue

When to Contact Your Developer/Host:

Admin performance issues typically require:

  • Hosting provider - For resource allocation, PHP configuration
  • Developer - For database optimization, code profiling

Getting Help

Section titled “Getting Help”

If you’ve tried the relevant troubleshooting steps and still have issues:

What to Gather

Section titled “What to Gather”

Before contacting support, gather this information:

  1. WordPress version: Go to Dashboard → Updates
  2. WooCommerce version: Go to Plugins → Installed Plugins
  3. SpecCart version: Go to Plugins → Installed Plugins
  4. PHP version: Go to Tools → Site Health → Info → Server
  5. Error messages: Screenshots of any errors (browser console, admin notices, customer-facing messages)
  6. What you’ve tried: List the troubleshooting steps you’ve already completed

Who to Contact

Section titled “Who to Contact”
  • Theme issues: Your theme developer or support
  • Server/hosting issues: Your hosting provider support
  • Plugin conflicts: Deactivate plugins to identify the conflict, then contact that plugin’s support
  • SpecCart bugs: Your developer, or file a bug report with all gathered information
  • Custom development needs: Your developer
Section titled “Related Resources”