> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftlywp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common issues with BoxBuilder.

## Builder Not Showing on Product Page

<AccordionGroup>
  <Accordion title="BoxBuilder tab not visible in product editor">
    Make sure WooCommerce is installed and activated. BoxBuilder requires WooCommerce to function. If WooCommerce is missing, BoxBuilder will deactivate itself.
  </Accordion>

  <Accordion title="Builder doesn't appear on the frontend">
    1. Check that **Enable BoxBuilder** is checked in the product's BoxBuilder tab
    2. Make sure the product is published (not draft)
    3. Check the **Builder Position** setting in **BoxBuilder → Settings → General** — try a different position
    4. If using a page builder, try the `[boxbuilder id="123"]` shortcode directly
    5. Check for JavaScript errors in the browser console (F12 → Console tab)
  </Accordion>

  <Accordion title="Builder shows but no products appear">
    1. Check the **Product Source** setting — make sure the selected categories/products have published, in-stock items
    2. If using "By Category", confirm your products are assigned to the selected categories
    3. If using "Specific Products", confirm the selected products are published and in stock
    4. Check that products have prices set — products without prices are excluded
  </Accordion>
</AccordionGroup>

## Cart Issues

<AccordionGroup>
  <Accordion title="Box items not showing in cart">
    Check **BoxBuilder → Settings → Cart → Show cart contents** — make sure it's set to "Yes".
  </Accordion>

  <Accordion title="Price is wrong in cart">
    1. For **Fixed pricing**: Make sure the box product has the correct price set in the WooCommerce General tab
    2. For **Per-item pricing**: Set the box product price to \$0.00 — the total should be the sum of selected items
    3. Clear the WooCommerce cart and add the box again
    4. Check if any other plugins are modifying cart prices (disable other plugins temporarily to test)
  </Accordion>

  <Accordion title="Items appear twice in cart">
    This can happen if another plugin is interfering with cart item visibility. BoxBuilder hides child items via the `woocommerce_cart_item_visible` filter. Check if another plugin is also hooking into this filter.
  </Accordion>
</AccordionGroup>

## Order Issues

<AccordionGroup>
  <Accordion title="Box contents not showing in order emails">
    1. Check that your email template is using standard WooCommerce order item display
    2. If you have a custom email template, make sure it supports order item meta display
    3. Test with the default WooCommerce email template by temporarily switching to the Storefront theme
  </Accordion>

  <Accordion title="Gift message not appearing in order">
    1. Make sure gift messages are enabled in **BoxBuilder → Settings → Gift Message**
    2. Check the order in admin — look for `_boxbuilder_message` in the order item meta
    3. The gift message is stored with the parent box order item, not as a separate order note
  </Accordion>
</AccordionGroup>

## Style Issues

<AccordionGroup>
  <Accordion title="Builder looks broken or unstyled">
    1. Clear your browser cache and any caching plugins
    2. Check if your theme is overriding BoxBuilder styles — try switching to Storefront temporarily
    3. Check for CSS conflicts using browser DevTools (F12 → Elements → Styles)
    4. Make sure no optimization plugin is stripping BoxBuilder's CSS file
  </Accordion>

  <Accordion title="Product images are blurry">
    1. Go to **Settings → Media** and check the thumbnail sizes
    2. Regenerate thumbnails using a plugin like [Regenerate Thumbnails](https://wordpress.org/plugins/regenerate-thumbnails/)
    3. Ensure your product images are large enough — BoxBuilder uses the WooCommerce thumbnail size
  </Accordion>
</AccordionGroup>

## Performance

<AccordionGroup>
  <Accordion title="Builder loads slowly">
    1. Reduce **Products Per Page** in settings (try 8 or 12 instead of 24+)
    2. Optimize your product images — use appropriate sizes, not full-resolution uploads
    3. Check if your hosting meets the minimum requirements
    4. Disable other plugins temporarily to identify conflicts
  </Accordion>
</AccordionGroup>

## Still Need Help?

If you can't resolve your issue:

1. Check the [FAQ](/plugins/boxbuilder/faq) for additional answers
2. Check [Compatibility](/plugins/boxbuilder/compatibility) for known plugin/theme interactions
3. [Contact Support](https://swiftlywp.com/support/) — include your WordPress version, WooCommerce version, theme name, and a description of the issue