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 1.0.0. 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.

    Conflict groups aren't blocking incompatible add-ons

    Conflict groups apply on the product page selection UI, not in the cart. If a customer added a second add-on through a non-standard path (REST, programmatic add-to-cart), the conflict won't be enforced. The Cart layer trusts the selection from the product page.

    For belt-and-suspenders enforcement, hook mcp_validate_add_to_cart and reject programmatically-built carts that violate your conflict policy.

    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.

    Filing a GitHub Issue

    Companion Products lives at [github.com/maxtdesign/maxtdesign-companion-products](https://github.com/maxtdesign/maxtdesign-companion-products/issues). When filing an issue, 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