Start a Project
View Categories

Troubleshooting Guide

9 min read

Table of Contents

Solutions to common issues and problems

Overview #

This guide provides solutions to the most common issues users encounter with Submittal & Spec Sheet Builder. Issues are organized by category for easy navigation.

Quick Diagnostics #

Before diving into specific issues, try these general troubleshooting steps:

1. Clear Browser Cache #

Many issues resolve after clearing cache:

  • Chrome: Ctrl+Shift+Delete → Clear browsing data
  • Firefox: Ctrl+Shift+Delete → Clear data
  • Safari: Cmd+Option+E → Empty caches
  • Edge: Ctrl+Shift+Delete → Clear browsing data

2. Disable Browser Extensions #

Extensions can interfere with plugin functionality:

  1. Open browser in incognito/private mode
  2. Test if issue persists
  3. If resolved, disable extensions one by one to find culprit

3. Check WordPress Debug Log #

Enable WordPress debugging to see error messages:

  1. Edit wp-config.php
  2. Add these lines to enable debug logging
  3. Check /wp-content/debug.log for errors

4. Test with Default Theme #

Theme conflicts are common:

  1. Switch to Twenty Twenty-Five (or another default theme)
  2. Test if issue persists
  3. If resolved, contact theme developer

5. Disable Other Plugins #

Plugin conflicts can cause issues:

  1. Deactivate all other plugins
  2. Test if issue persists
  3. Reactivate plugins one by one to identify conflict

PDF Generation Issues #

PDF Generation Fails #

Symptoms:

  • Error message appears
  • Loading spinner never stops
  • “Failed to generate PDF” message

Cause 1: Server Timeout #

Error: “Maximum execution time exceeded”

Solution: Increase PHP execution time via .htaccess, php.ini, or wp-config.php. Contact hosting support if you don’t have access to these files.

Cause 2: Memory Limit #

Error: “Allowed memory size exhausted”

Solution: Increase PHP memory limit by adding to wp-config.php, .htaccess, or php.ini. Recommended: 256MB minimum, 512MB for large catalogs.

Cause 3: Missing PHP Extensions #

Error: “Required PHP extension missing”

Required Extensions:

  • mbstring
  • gd or imagick
  • dom
  • libxml

Solution: Contact hosting provider to enable missing extensions.

Cause 4: File Permission Issues #

Error: “Failed to write file” or “Permission denied”

Solution: Check folder permissions (should be 755) and file permissions (should be 644). On Windows servers: Ensure IIS user has write permissions.

PDF Generation is Very Slow #

Symptoms:

  • Takes 30+ seconds to generate
  • Server becomes unresponsive
  • Browser times out

Solutions:

  • Reduce Products Per Packet – Generate smaller packets (10-15 products max), split large submittals into multiple PDFs
  • Optimize Server Resources – Upgrade hosting plan, increase PHP memory/execution limits, use dedicated server or VPS
  • Disable Product Images – Go to Settings → Frontend, uncheck “Show Product Thumbnails” (images increase generation time)
  • Use DomPDF Engine – Go to Settings → PDF, select “DomPDF” (faster than TCPDF)

PDF is Blank or Missing Content #

Symptoms:

  • PDF downloads but shows blank pages
  • Missing product data
  • Only cover page appears

Solutions:

  • Check Product Data – Verify products have specifications filled in, ensure complete hierarchy exists, test with different products
  • Verify Branding Settings – Ensure logo uploaded successfully, check brand color is set, verify company information is complete
  • Test with Minimal Setup – Generate PDF with just 1-2 products to isolate the issue
  • Check Console for Errors – Open browser DevTools (F12), look for JavaScript errors, check Network tab for failed requests

PDF Formatting Issues #

Symptoms:

  • Text overlaps
  • Tables cut off
  • Poor alignment
  • Fonts look wrong

Solutions:

  • Page Size Mismatch – Go to Settings → PDF → Page Size, ensure correct size selected (Letter vs A4)
  • Long Product Names – Shorten product model names if excessively long, use abbreviations where appropriate
  • Browser-Specific Rendering – Try opening PDF in different browser, download PDF and open in Adobe Reader
  • Try Different Theme (Pro) – Go to Settings → PDF, select different PDF theme (some handle long content better)

Frontend Builder Issues #

Products Not Displaying #

Symptoms:

  • Builder page shows “No products found”
  • Product gallery is empty
  • Search returns no results

Solutions:

  • Verify Products Exist – Go to Admin → Submittal Builder → Catalog Builder, ensure products are added and visible, check that models have specifications
  • Check Product Hierarchy – Products must have: Category → Product → Type → Model. Missing levels prevent display.
  • Clear Cache – Clear browser cache, if using caching plugin clear its cache, regenerate page
  • Check Shortcode – Verify page contains [submittal_builder], check for typos, ensure shortcode is not inside quotes
  • JavaScript Errors – Open browser console (F12), look for red error messages (often indicates plugin/theme conflicts)

Search Not Working #

Symptoms:

  • Typing in search box does nothing
  • Results don’t filter
  • Search box grayed out

Solutions:

  • Enable Search in Settings – Go to Admin → Settings → General → Enable Search, ensure checkbox is checked
  • Check for JavaScript Errors – Open browser console (F12), look for errors related to search
  • Update Browser – Ensure browser is updated to latest version, try different browser to test
  • Disable Conflicting Plugins – Some plugins interfere with AJAX search, temporarily disable to test

Can’t Select Products #

Symptoms:

  • Clicking products doesn’t select them
  • Selection count doesn’t update
  • “Continue” button grayed out

Solutions:

  • Enable JavaScript – Verify JavaScript is enabled in browser, check browser settings, some security plugins disable JavaScript
  • Clear Browser Cache – Often resolves selection issues. Hard refresh: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
  • Check Console for Errors – Open DevTools (F12), look for JavaScript errors
  • Test Different Browser – Try Chrome, Firefox, or Edge. If works in one browser, issue is browser-specific.

Images/Thumbnails Not Showing #

Symptoms:

  • Product cards show broken image icons
  • Thumbnails missing in gallery view

Solutions:

  • Ensure Feature Enabled – Go to Settings → Frontend → Show Product Thumbnails, verify checkbox is checked
  • Verify Product Images Uploaded – Each product needs featured image, go to Catalog Builder and add images to products
  • Check Image Permissions – Ensure image files have proper permissions (644)
  • Test with Different Product – If only some images missing, issue may be specific product image

Admin Issues #

Catalog Builder Won’t Load #

Symptoms:

  • Catalog Builder page blank
  • Loading spinner never stops
  • JavaScript errors in console

Solutions:

  • Clear Browser Cache – Hard refresh page, try different browser
  • Disable Plugins – Deactivate conflicting plugins one by one
  • Check PHP Errors – Enable WordPress debug, check /wp-content/debug.log
  • Verify REST API Working – Visit: yoursite.com/wp-json/sfb/v1/nodes, should see JSON data not error

Settings Won’t Save #

Symptoms:

  • Click “Save Changes” but settings revert
  • No success message appears
  • Changes don’t persist

Solutions:

  • Check for Error Messages – Look for red error notices at top of admin page, check browser console for JavaScript errors
  • Verify User Permissions – Must be Administrator, check user role in Users → Your Profile
  • Disable Security Plugins Temporarily – Security plugins can block POST requests
  • Check for Plugin Conflicts – Deactivate other plugins one by one to identify conflict

License & Activation Issues #

License Key Won’t Activate #

Symptoms:

  • “Invalid license key” error
  • Activation fails
  • Pro features not unlocking

Solutions:

  • Verify License Key – Copy key carefully from purchase email, avoid extra spaces before/after, check for missing characters
  • Check Site URL – License tied to specific domain, verify you’re on correct site, contact support to change domain
  • Maximum Activations Reached – Pro Single Site: 1 site max, Pro Agency: 5 sites max. Deactivate on unused sites first.
  • License Expired – Check renewal date in purchase email, renew to restore access
  • Check Internet Connection – Activation requires connection to license server, verify server can reach external APIs

Pro Features Not Working #

Symptoms:

  • License shows active but features disabled
  • Tracking page not accessible
  • Lead capture not showing

Solutions:

  • Verify License Tier – Free: No Pro features, Pro Single Site: Pro features only, Pro Agency: All features
  • Reactivate License – Deactivate license, wait 30 seconds, reactivate to force refresh
  • Clear Cache – Clear WordPress object cache, clear browser cache, deactivate caching plugins temporarily
  • Check Feature Settings – Some Pro features require manual enablement in Settings → Pro

Performance Issues #

Slow Page Load Times #

Symptoms:

  • Frontend builder takes 5+ seconds to load
  • Admin pages slow
  • Browser becomes unresponsive

Solutions:

  • Enable Caching – Settings → Advanced → Enable Caching
  • Reduce Products Per Page – Settings → General → Products Per Page, lower to 25-50 for large catalogs
  • Optimize Images – Settings → Advanced → Optimize Images
  • Use Caching Plugin – Install WP Super Cache or W3 Total Cache, configure page caching
  • Upgrade Hosting – VPS or managed WordPress hosting recommended, at least 2GB RAM for 500+ products

High Memory Usage #

Symptoms:

  • “Memory exhausted” errors
  • Server crashes
  • Very slow performance

Solutions:

  • Increase PHP Memory – Increase memory limit in wp-config.php, .htaccess, or php.ini
  • Reduce Catalog Size – Remove unused products, archive old products, split into multiple catalogs
  • Disable Product Images – Images consume significant memory, disable in Settings → Frontend
  • Optimize Database – Use plugin like WP-Optimize, clean up post revisions and transients

Browser-Specific Issues #

Issues in Internet Explorer #

Status: Internet Explorer is not supported.

Solution: Use modern browser: Google Chrome (recommended), Mozilla Firefox, Microsoft Edge, or Safari.

Issues in Safari #

Common Issues:

  • PDF download prompts multiple times
  • Visual glitches in builder

Solutions:

  • Update Safari to latest version
  • Clear Safari cache: Cmd+Option+E
  • Disable Safari extensions
  • Try Chrome or Firefox as alternative

Issues on Mobile #

Common Issues:

  • Touch targets too small
  • Drag and drop not working
  • PDF generation slow

Solutions:

  • Use tablet instead of phone when possible
  • Switch to landscape mode
  • Reduce number of products per PDF
  • Download PDF via desktop computer for best results

Error Messages Explained #

“Nonce verification failed” #

Meaning: Security token expired or invalid.

Solution: Refresh page and try again, clear browser cache, log out and log back in.

“You do not have permission” #

Meaning: User lacks required capabilities.

Solution: Ensure logged in as Administrator, check user role in Users → Your Profile, contact site admin if not administrator.

“REST API error” #

Meaning: WordPress REST API not accessible.

Solution: Verify REST API enabled in Settings → Advanced, check if security plugin blocking API, test by visiting yoursite.com/wp-json/

“File upload failed” #

Meaning: Server couldn’t save uploaded file.

Solution: Check file permissions, verify disk space available, check PHP upload limits (upload_max_filesize, post_max_size).

Getting Additional Help #

If issues persist after trying solutions above:

Before Contacting Support #

  1. Note Error Messages – Exact wording of errors, when they occur, steps to reproduce
  2. Check Debug Log – Enable WP_DEBUG, check /wp-content/debug.log, copy relevant error lines
  3. Gather System Info – WordPress version, PHP version, plugin version, active theme, active plugins
  4. Test in Isolation – Default theme, minimal plugins, does issue persist?

Support Channels #

WordPress.org Forum: Community Support

Pro Email Support: support@webstuffguylabs.com (Pro license holders)

Include in Support Request:

  • Description of issue
  • Steps to reproduce
  • Error messages (exact wording)
  • System information
  • Screenshots if applicable

Prevention Tips #

Regular Maintenance #

✅ Do:

  • Keep WordPress updated
  • Keep PHP updated
  • Update plugin when new version released
  • Regular database optimization
  • Weekly backups

❌ Don’t:

  • Use outdated software
  • Ignore update notices
  • Skip backups
  • Use unsupported PHP versions

Best Practices #

✅ Do:

  • Use modern browsers
  • Clear cache regularly
  • Test changes on staging site first
  • Monitor error logs
  • Use quality hosting

❌ Don’t:

  • Use Internet Explorer
  • Install conflicting plugins
  • Ignore performance issues
  • Disable security features without reason
What are your Feelings