BigCommerce Troubleshooting Overview | Blue Frog Docs

BigCommerce Troubleshooting Overview

Comprehensive troubleshooting guide for BigCommerce performance and tracking issues.

BigCommerce Troubleshooting Overview

Diagnose and resolve common BigCommerce issues affecting performance, tracking, and user experience. This guide covers platform-specific challenges and solutions.

Common Issue Categories

Performance Issues

BigCommerce stores can experience performance challenges that impact Core Web Vitals and user experience:

Common Causes:

  • Unoptimized images not using Akamai CDN features
  • Render-blocking JavaScript and CSS
  • Third-party scripts (analytics, chat widgets, review apps)
  • Large theme files or poorly optimized Stencil code
  • Too many apps installed

Tracking and Analytics Issues

Problems with analytics and marketing pixel implementation:

  • Events Not Firing: Tags or events not triggering correctly
  • Missing Data: Incomplete or inaccurate tracking data
  • Duplicate Events: Same event firing multiple times
  • Checkout Tracking: Issues tracking checkout and purchase events

Common Causes:

  • Script Manager configuration errors
  • Incorrect Stencil template integration
  • GTM trigger or variable issues
  • Adblocker interference
  • Checkout script limitations on Standard plans

Theme and Display Issues

Visual and functional problems with store appearance:

  • Content not displaying correctly
  • Responsive design failures on mobile
  • Cart or checkout errors
  • Product options not working
  • Custom code conflicts

Common Causes:

  • Theme compatibility issues
  • JavaScript errors in custom code
  • Browser caching problems
  • Stencil compilation errors
  • App conflicts

BigCommerce-Specific Constraints

Understanding platform limitations helps troubleshoot more effectively.

Checkout Customization Limitations

BigCommerce's Optimized One-Page Checkout:

  • Hosted separately from main storefront
  • Limited template access (no full HTML/CSS editing)
  • Script injection only available on Plus, Pro, Enterprise plans
  • PCI compliance restrictions on checkout modifications

Implications:

  • Checkout tracking requires checkout scripts feature
  • Custom checkout design options are limited
  • Some tracking implementations only work on higher-tier plans

Blueprint vs. Stencil Themes

Blueprint (Legacy):

  • PHP-based, older framework
  • Limited modern features
  • Reduced BigCommerce support
  • Not recommended for new implementations

Stencil (Current):

  • Handlebars.js templating
  • Full access to BigCommerce APIs
  • Required for modern features
  • Better performance and flexibility

Troubleshooting Tip: If using Blueprint, many issues can be resolved by migrating to Stencil.

Akamai CDN Integration

BigCommerce uses Akamai CDN for content delivery:

Benefits:

  • Automatic image optimization (if enabled)
  • Global content distribution
  • DDoS protection
  • SSL/TLS termination

Troubleshooting Considerations:

  • CDN caching can delay script changes
  • Image optimization settings affect LCP
  • Purge cache when testing changes
  • Verify Akamai Image Manager is enabled

App Marketplace Limitations

App Installation Considerations:

  • Each app adds HTTP requests and potential performance overhead
  • Apps may conflict with each other
  • Some apps inject code that can't be easily modified
  • Removing apps may leave residual code in theme

Best Practice: Audit installed apps regularly and remove unused ones.

Diagnostic Tools and Resources

BigCommerce Native Tools

Store Performance:

  • Server Settings > Performance: Clear cache, manage redirects
  • Channel Manager: View sales channel integrations
  • Store Logs: System logs for errors (contact support)

Developer Tools:

  • Stencil CLI: Local development and debugging
  • Store Design > Themes: Theme management and rollback
  • Storefront API: GraphQL and REST APIs for data access

Browser Developer Tools

Essential for Debugging:

  1. Console Tab:

    • JavaScript errors
    • Console logs from tracking scripts
    • Warning messages

  2. Network Tab:

    • HTTP requests and responses
    • Script loading times
    • Failed requests
    • Analytics pixel requests

  3. Performance Tab:

    • Page load timeline
    • Rendering performance
    • JavaScript execution time

  4. Application Tab:

    • Cookies
    • Local storage
    • Session storage

Third-Party Diagnostic Tools

Performance Testing:

Tracking Verification:

SEO and Accessibility:

General Troubleshooting Workflow

Step 1: Identify the Issue

  1. Reproduce the problem:

    • Document exact steps to trigger the issue
    • Test on multiple browsers (Chrome, Firefox, Safari, Edge)
    • Test on different devices (desktop, mobile, tablet)
    • Try incognito/private mode to rule out browser extensions

  2. Gather information:

    • When did the issue start?
    • Were any recent changes made (theme updates, app installations, Script Manager changes)?
    • Does it affect all users or specific segments?
    • Is it page-specific or site-wide?

Step 2: Check BigCommerce Status

  1. Visit BigCommerce Status Page

    • Check for platform-wide issues
    • Review recent incidents
    • Subscribe to status updates

  2. Check Akamai CDN Status

    • Verify no CDN outages or issues
    • Confirm content delivery is functioning

Step 3: Review Recent Changes

  1. Theme Changes:

    • Check Store Design > Themes > My Themes
    • Review recent theme updates or customizations
    • Consider rolling back to previous version if issue started after theme change

  2. Script Manager:

    • Review Storefront > Script Manager
    • Check recently added or modified scripts
    • Temporarily disable scripts to isolate issues

  3. App Installations:

    • Review Apps > My Apps
    • Identify recently installed or updated apps
    • Temporarily disable apps to test

Step 4: Clear Caches

BigCommerce uses multiple cache layers:

  1. Store Cache:

    • Go to Server Settings > Performance
    • Click Clear Store Cache

  2. Browser Cache:

    • Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
    • Clear browser cache completely
    • Test in incognito mode

  3. CDN Cache:

    • Clearing store cache also purges CDN cache
    • Allow 5-10 minutes for full propagation

Step 5: Check Browser Console

  1. Open Developer Tools:

    • Chrome/Edge: F12 or Ctrl+Shift+I (Cmd+Opt+I on Mac)
    • Firefox: F12 or Ctrl+Shift+I
    • Safari: Enable Dev Tools, then Cmd+Opt+I

  2. Review Console Tab:

    • Look for red error messages
    • Note which scripts are causing errors
    • Check if errors correlate with the issue

  3. Review Network Tab:

    • Check for failed requests (red status codes)
    • Identify slow-loading resources
    • Verify analytics scripts are loading

Step 6: Test with Minimal Configuration

Isolate the Problem:

  1. Switch to default theme:

    • Apply a default BigCommerce theme
    • Test if issue persists
    • If resolved, issue is theme-related

  2. Disable all Script Manager scripts:

    • Temporarily disable all scripts
    • Test if issue persists
    • Re-enable one at a time to identify culprit

  3. Disable apps:

    • Temporarily uninstall apps
    • Test if issue persists
    • Reinstall one at a time to identify conflicting app

Step 7: Document and Test Fix

  1. Document the solution:

    • Record what caused the issue
    • Document the fix applied
    • Note any configuration changes

  2. Test thoroughly:

    • Test across multiple browsers and devices
    • Verify the fix doesn't break other functionality
    • Monitor for 24-48 hours to ensure stability

  3. Communicate changes:

    • Notify team of changes made
    • Update documentation
    • Log in version control if applicable

When to Contact BigCommerce Support

Contact BigCommerce support when:

  • Platform Issues: Issues with BigCommerce core functionality (checkout broken, admin panel errors)
  • Server-Side Errors: 500 errors, database connection issues
  • Account Issues: Billing, plan changes, store access
  • API Issues: Problems with BigCommerce APIs
  • Data Issues: Missing orders, customer data problems

How to Contact:

  • Phone: Available for Plus, Pro, Enterprise plans
  • Email/Ticket: All plans
  • Priority Support: Available for Enterprise plans

What to Provide:

  • Store URL
  • Detailed description of issue
  • Steps to reproduce
  • Screenshots or screen recordings
  • Browser and device information
  • Any recent changes made

When to Hire a Developer

Consider hiring a BigCommerce developer for:

  • Complex Stencil Customizations: Advanced theme development
  • Custom App Development: Building custom integrations
  • Performance Optimization: In-depth performance tuning
  • Migration Projects: Moving from Blueprint to Stencil, or from another platform
  • Complex Integrations: ERP, PIM, custom payment gateways
  • Headless Commerce: Custom frontend development

Finding BigCommerce Developers:

Prevention Best Practices

Regular Maintenance

  1. Keep themes updated:

    • Update to latest theme version
    • Review changelogs before updating
    • Test updates in staging environment if available

  2. Audit apps quarterly:

    • Remove unused apps
    • Update active apps
    • Monitor app performance impact

  3. Review Script Manager:

    • Remove unused scripts
    • Optimize script loading order
    • Update tracking code as platforms evolve

Monitoring

  1. Set up alerts:

  2. Regular performance checks:

    • Monthly PageSpeed Insights audits
    • Monitor Core Web Vitals trends in Search Console
    • Review GTmetrix or WebPageTest reports

  3. Analytics monitoring:

    • Weekly traffic reviews
    • Monitor conversion rate trends
    • Check for tracking anomalies

Testing Before Changes

  1. Use Stencil CLI for local development:

    • Test theme changes locally before deployment
    • Validate Handlebars syntax
    • Check for JavaScript errors

  2. Backup themes before major changes:

    • Download theme file before modifications
    • Note theme version and customizations

  3. Test in preview mode:

    • Use BigCommerce theme preview
    • Test across devices and browsers
    • Verify tracking still functions

Quick Reference: Common Issues

Symptom Likely Cause Quick Fix
Analytics not tracking Script Manager inactive or GTM not loaded Verify scripts are active, check browser console
Slow page load Unoptimized images, too many apps Enable image optimization, audit apps
Layout shifting Images without dimensions, late-loading content Add width/height attributes, optimize loading
Checkout tracking not working Plan doesn't support checkout scripts Upgrade plan or use conversion tracking code
404 errors Broken redirects, deleted products Check redirect settings, verify URLs
Theme changes not appearing Cache not cleared Clear store cache, hard refresh browser

Next Steps

Explore specific troubleshooting guides:

Additional Resources

↑ Back to top
// SYS.FOOTER