> ## 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

> [accordion] 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] 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] 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

## Cart Issues

> [accordion] Box items not showing in cart
>
> Check **BoxBuilder → Settings → Cart → Show cart contents** — make sure it's set to "Yes".

> [accordion] 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] 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.

## Order Issues

> [accordion] 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] 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

## Style Issues

> [accordion] 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] 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

## Performance

> [accordion] 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

## Still Need Help?

If you can't resolve your issue:

1. Check the [FAQ](https://docs.swiftlywp.com/plugins/boxbuilder/faq.md) for additional answers
2. Check [Compatibility](https://docs.swiftlywp.com/plugins/boxbuilder/compatibility.md) 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.