Troubleshooting Guide

This guide provides step-by-step diagnostic procedures for resolving common theme issues.

Installation Issues

Theme Upload Fails

Symptoms: Error message, upload stalls, theme doesn’t appear after upload.

Diagnostic Steps:

1. Verify file: Ensure it’s a .zip file under 50MB, not corrupted
2. Try different browser: Use Chrome in incognito mode
3. Disable extensions: Temporarily disable ad blockers
4. Check connection: Try a more stable internet connection
5. Check plan: Shopify Starter doesn’t support custom themes

Cause	Solution	Success Rate
Corrupted download	Re-download from email	85%
Browser extension	Use incognito mode	70%
Shopify Starter plan	Upgrade to Basic	100%
Network timeout	Use faster connection	60%

Performance Problems

Slow Page Load

1. Run PageSpeed Insights to identify bottlenecks
2. Check Theme Settings — disable unused features
3. Audit installed apps (each app can add 100-500ms)
4. Optimize images (compress, use appropriate sizes)
5. Check for third-party scripts blocking rendering

High Cumulative Layout Shift (CLS)

1. Ensure images have width and height attributes
2. Check for late-loading ads or embeds
3. Verify fonts use font-display: swap
4. Test with Lighthouse in Chrome DevTools

Display & Layout Issues

Content Not Showing

1. Verify the section is added to the page template
2. Check if the feature is enabled in Theme Settings
3. Clear browser cache and hard refresh
4. Try a different browser
5. Check theme is published (not just in draft)

Mobile Layout Problems

1. Test on actual mobile devices (not just browser resize)
2. Check viewport settings in browser DevTools
3. Verify responsive settings in the theme
4. Look for CSS conflicts with apps

Colors Don’t Match Brand

1. Go to Theme Settings > Colors
2. Update primary, secondary, and accent colors
3. Check individual section color overrides
4. Verify color contrast meets WCAG AA (4.5:1 minimum)

Feature-Specific Issues

Quick View Not Working

1. Check Theme Settings > Quick View is enabled
2. Verify product cards have the quick view trigger
3. Check browser console for JavaScript errors
4. Test with apps disabled

Free Shipping Bar Not Updating

1. Verify threshold is set correctly (in dollars, not cents)
2. Check position setting (Cart, Header, or Floating)
3. Clear browser cache
4. Test cart operations

Exit Popup Not Appearing

1. Check Theme Settings > Exit Popup is enabled
2. Clear localStorage: localStorage.removeItem('exitPopupShown')
3. Test in incognito mode (fresh session)
4. Verify delay setting isn’t too long
5. Test mouse-leave detection (move mouse to top of browser)

Search Not Returning Results

1. Verify products exist and are published
2. Check Theme Settings > Search is enabled
3. Type at least 2 characters
4. Check browser console for API errors

Integration & App Conflicts

App Breaking Theme Layout

1. Disable the app temporarily
2. Check if issue resolves
3. Contact the app developer about compatibility
4. Check for CSS/JavaScript conflicts in browser DevTools

Checkout Issues

1. Checkout is controlled by Shopify, not the theme
2. Check Shopify payment settings
3. Verify shipping zones are configured
4. Contact Shopify Support for checkout-specific issues

Browser-Specific Issues

Safari Display Problems

• Clear Safari cache: Develop > Empty Caches
• Check for CSS flexbox/grid compatibility
• Verify no -webkit- prefix issues

Firefox Rendering Issues

• Check for CSS Grid compatibility
• Verify font rendering
• Test with other Firefox extensions disabled

Emergency Procedures

Theme Completely Broken

1. Don’t panic — your data is safe
2. Switch to a backup theme: Online Store > Themes > Actions > Publish on your old theme
3. Report the issue to theme support with browser console errors
4. Wait for a fix before switching back

Lost Customizations

1. Check if you have a theme backup
2. Use Shopify’s theme version history: Themes > Actions > Download theme file
3. Compare JSON settings between versions
4. Re-apply lost settings manually