Troubleshooting Guide

Solutions to common issues and problems you might encounter.

Quick Diagnostics

Before diving into specific issues:

1. Clear cache: Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
2. Check console: Open browser DevTools (F12) → Console
3. Verify installation: Check app block is added in theme
4. Test incognito: Try private/incognito browsing mode

Display Issues

Customizer Not Appearing

Symptoms:

• Product page shows no add-on options
• Only default product form visible

Solutions:

1. Check App Block
   • Go to Theme Customizer
   • Select a product page
   • Look for Uplift app block
   • Add if missing
2. Verify Product Assignment
   • Go to Uplift admin
   • Check product has add-on groups
   • Ensure groups are enabled
3. Theme Compatibility
   • Some themes need manual integration
   • Check theme documentation
   • Contact support for help

Styling Issues

Symptoms:

• Options look broken or misaligned
• Colors don't match theme

Solutions:

1. Check CSS Conflicts
   • Open browser DevTools
   • Inspect affected elements
   • Look for overriding styles
2. Theme Customization
   • Use theme settings if available
   • Add custom CSS in theme editor
   • Adjust margins/padding
3. Reset Styles
   • Clear any custom CSS
   • Restore default settings
   • Rebuild from clean state

Swatches Not Showing Colors

Symptoms:

• Swatch boxes are empty or white
• Colors not rendering

Solutions:

1. Verify Color Values
   • Check hex codes are valid (#RRGGBB)
   • Don't include extra characters
   • Example: #FF5733 not #FF5733;
2. Check Image URLs
   • If using images, verify URLs work
   • Test URL directly in browser
   • Use publicly accessible URLs

Pricing Issues

Prices Not Updating

Symptoms:

• Product price doesn't change when selecting options
• Add-on prices not reflecting

Solutions:

1. Check Product Links
   • Verify linked products have prices
   • Check variant pricing
   • Ensure products are active
2. JavaScript Errors
   • Open browser console
   • Look for error messages
   • Fix or report errors
3. Theme Conflict
   • Some themes handle pricing differently
   • Check for price update scripts
   • May need custom integration

Wrong Prices Displaying

Symptoms:

• Prices don't match expected values
• Currency or format wrong

Solutions:

1. Verify Source Prices
   • Check linked product in Shopify
   • Verify variant price
   • Account for currency settings
2. Check Shopify Settings
   • Settings → General → Currency
   • Verify format settings
   • Check tax display preferences

Cart Issues

Add-ons Not Appearing in Cart

Symptoms:

• Main product added, but no add-ons
• Missing line items

Solutions:

1. Check Product Links
   • Go to Uplift admin
   • Verify products are linked
   • Ensure linked products are published
2. Inventory Issues
   • Check add-on product inventory
   • Ensure "Continue selling when out of stock" if needed
   • Verify product status is Active
3. Theme Cart Integration
   • Some AJAX carts need updates
   • Check cart template includes all items
   • May need cart page refresh

Duplicate Items in Cart

Symptoms:

• Same add-on appears multiple times
• Unexpected line items

Solutions:

1. Clear Cart and Retry
   • Remove all items
   • Add product fresh
   • Check cart again
2. Check for Double Submission
   • Disable any rapid-click on add button
   • Check for JavaScript conflicts
   • Verify form isn't submitting twice

Cart Properties Missing

Symptoms:

• Customization details not showing
• No selection information

Solutions:

1. Check Theme Cart Template
   • Properties need to be displayed in template
   • Look for item.properties in cart code
   • May need theme customization
2. Verify Selection Made
   • Ensure options were selected before adding
   • Required fields must be completed
   • Check for validation bypass

Canvas Issues

Canvas Not Loading

Symptoms:

• Empty space where canvas should be
• No visual preview

Solutions:

1. Check Image URLs
   • Verify base image exists
   • Check layer image URLs
   • Test URLs directly in browser
2. JavaScript Errors
   • Open browser console
   • Look for canvas-related errors
   • Check for missing libraries
3. Browser Support
   • Canvas requires modern browser
   • Update browser if old
   • Check WebGL support

Canvas Layers Wrong Order

Symptoms:

• Images stacking incorrectly
• Elements appearing behind/in front incorrectly

Solutions:

1. Reorder in Admin
   • Go to canvas configuration
   • Drag layers to correct order
   • Save and refresh
2. Check Layer Settings
   • Verify z-index if manually set
   • Review layer visibility rules
   • Check conditional display

Canvas Performance Issues

Symptoms:

• Slow loading or updates
• Choppy animations

Solutions:

1. Optimize Images
   • Use appropriate image sizes
   • Compress images (PNG/WebP)
   • Reduce number of layers
2. Device Limitations
   • Mobile may be slower
   • Reduce complexity for mobile
   • Consider lazy loading

Conditional Logic Issues

Options Not Hiding/Showing

Symptoms:

• Conditions don't trigger
• Options always visible/hidden

Solutions:

1. Verify Rule Configuration
   • Check trigger condition is correct
   • Verify target is properly set
   • Test with simple conditions first
2. Check Option IDs
   • Rules use internal IDs
   • If options were recreated, update rules
   • Delete and recreate rule if needed
3. Multiple Conditions
   • All conditions must be true (AND)
   • Verify each condition individually
   • Simplify to isolate issue

Conditional Options Still Validating

Symptoms:

• Hidden required fields blocking submission
• Validation errors for invisible options

Solutions:

1. Check Hide Behavior
   • Hidden options should skip validation
   • This should be automatic
   • Contact support if persists

Order Issues

Missing Customization in Orders

Symptoms:

• Order doesn't show selections
• Properties not visible

Solutions:

1. Check Order Details
   • Some properties are hidden (underscore prefix)
   • Check line item properties section
   • Expand all details
2. Verify Cart Had Properties
   • Check cart before order was placed
   • Ensure theme displays properties
   • May need template update

Add-on Products Missing from Order

Symptoms:

• Only main product in order
• Expected line items missing

Solutions:

1. Check During Checkout
   • Verify items in cart before checkout
   • Complete checkout flow properly
   • Don't remove items mid-checkout
2. Inventory Issues
   • If add-on went out of stock during checkout
   • Check inventory at order time
   • Review Shopify order timeline

Theme-Specific Issues

Dawn Theme

Common fixes:

• Ensure app block added to product template
• Check sections/product-template.liquid
• May need to enable app embeds

Debut Theme

Common fixes:

• Legacy theme may need manual integration
• Add custom liquid code
• Contact support for specifics

Custom Themes

General approach:

1. Check app block compatibility
2. Review theme's product form
3. May need custom CSS
4. JavaScript conflicts possible

Browser-Specific Issues

Safari

Common issues:

• Flex layout differences
• Form submission timing
• Cache more aggressive

Solutions:

• Force refresh
• Clear Safari cache
• Test specific CSS

Firefox

Common issues:

• Form validation differences
• Image loading order

Solutions:

• Clear cache
• Check for specific CSS needs

Mobile Browsers

Common issues:

• Touch event handling
• Viewport sizing
• Performance limitations

Solutions:

• Test on actual devices
• Use responsive design
• Optimize for mobile

Error Messages

"Product not found"

Cause: Linked product deleted or unpublished

Solution:

1. Check product exists in Shopify
2. Verify product is published
3. Update product link in Uplift

"Inventory unavailable"

Cause: Add-on product out of stock

Solution:

1. Restock product
2. Enable "Continue selling when out of stock"
3. Hide option if intentional

"Invalid selection"

Cause: Required option not selected

Solution:

1. Make required selection
2. Check all required fields
3. Verify validation is working

Getting Help

Before Contacting Support

Gather this information:

1. Store URL
2. Product(s) affected
3. Browser and device
4. Screenshots of issue
5. Browser console errors

Contacting Support

• Include all diagnostic info
• Steps to reproduce
• Expected vs actual behavior

Preventive Measures

Regular Maintenance

1. Test after theme updates
2. Check after Shopify updates
3. Monitor for customer reports
4. Review orders for issues

Best Practices

1. Keep configurations simple
2. Test all changes
3. Use staging/development store
4. Document your setup

Next Steps

• FAQ - Common questions answered
• Quick Start Guide - Start fresh