MaxtDesign

Troubleshooting

"Companion Products requires WooCommerce" admin notice

The plugin does not initialise without WooCommerce. Install and activate WooCommerce first, then the notice disappears and the meta box appears on product edit screens.

Required selection isn't enforced on the product page

Check, in order:

  • 1.Product type — only simple products are supported in this release. Variable parents and grouped products are on the roadmap.
  • 2.Meta box — open the product editor and confirm Enable required product selection for this product is ticked and at least one companion is configured.
  • 3.Cache — go to WooCommerce → Settings → Companion Products → Tools → Clear Cache. The requirements lookup is cached for 1 hour and auto-invalidated on product save, but if you edited via direct database write or another plugin manipulated the postmeta, a manual flush is the cleanest reset.
  • 4.Theme overrides — some themes ship a custom single-product template that strips WooCommerce hooks. The selection UI is rendered on woocommerce_before_add_to_cart_button — if your theme doesn't fire that hook, the UI never appears. Switch to Storefront briefly to confirm.

    • Cart shows "Required for" but the relationship doesn't survive to the order

    The relationship is written to order line item meta during woocommerce_checkout_create_order_line_item. If you've replaced or short-circuited that hook (custom checkout plugin, headless checkout, REST checkout via the Store API) the meta may never be written. Check System Status for the order context and confirm _mcp_parent_product_id is present on the relevant line item.

    Quantity matching isn't working

    The cart enforces matching via woocommerce_after_cart_item_quantity_update and friends. If another plugin (most often a "free gift" or "bundle" plugin) is fighting for the same cart line, the last writer wins. Disable other cart manipulation plugins one at a time and re-test.

    Incompatibility rules aren't blocking conflicting add-ons

    Incompatibility rules dim and explain conflicts on the product page selection UI, and the cart re-validates the same rules server side at add-to-cart. If a customer reaches the cart through a non-standard path (REST, programmatic add-to-cart) the product-page dimming is skipped, but the server-side check still rejects an invalid combination.

    If a conflict still slips through, confirm both add-ons are marked in each other's "Incompatible with" list (rules are direct pairs, there is no chaining), then clear the cache under Tools. For extra enforcement on custom flows, hook mcp_validate_add_to_cart.

    WooCommerce Blocks cart shows companions but the label is missing

    Known issue with Blocks cart. The classic [woocommerce_cart] shortcode is fully supported. Blocks cart renders via React and the Store API, which bypasses the PHP woocommerce_get_item_data filter the plugin uses for cart-line metadata. Basic line item display works; the relationship label may not.

    If you're committed to Blocks cart, watch the GitHub issue tracker for the Store API integration roadmap.

    "Could not write order line item meta" in the debug log

    This usually means the order was created via a path that doesn't pass through woocommerce_checkout_create_order_line_item. Common culprits: REST API order creation, subscription renewals, manual orders created in admin without the standard checkout flow. Check the order's created_via value.

    For manual admin orders, line items can be linked retroactively by setting _mcp_parent_product_id on the companion line via $item->add_meta_data() and saving.

    Cache stats look stale in System Status

    Cache stats are read each time the System Status tab loads. If the numbers look frozen, the transient backend may be misbehaving (object cache plugin with broken delete(), transient table corrupted). Try Tools → Clear Cache and reload System Status.

    Debug Mode

    Enable WordPress debug mode to surface plugin warnings:

    // wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

    Check wp-content/debug.log for MCP_* warnings.

    Reporting an Issue

    While Companion Products is in private beta, report issues through the [contact page](/contact). When you reach out, include:

  • WordPress version, WooCommerce version, PHP version
  • HPOS state (legacy or custom order tables)
  • The System Status tab output (copy-paste verbatim)
  • A minimal reproduction: which product, which companion configuration, what you clicked, what you expected, what happened
  • Theme name (or confirmation that you reproduced on Storefront)
  • Any plugins manipulating the cart or checkout
  • debug.log excerpts if WP_DEBUG is on
    • Developer Guide