Check Product Add-Ons health and compatibility
The POM Product Add-Ons health panel gives store managers an actionable, privacy-safe view of the module before a migration, after a configuration change, or while investigating a storefront problem. It separates routine status checks from deeper catalog inspection so opening Site Health does not scan all Product Add-On definitions.
Before you begin
- WooCommerce and the Product Add-Ons POM Tweak must be active.
- You need access to WordPress Site Health to view the panel.
- You need permission to manage WooCommerce to run a deep diagnostic or rebuild derived data.
- On multisite, open the administration area for the site you want to inspect. Reports and maintenance actions apply only to that site.
Open the panel
- Go to Tools → Site Health.
- Select the POM Product Add-Ons tab.
- Review Current status and Known compatibility.
The current status reports the WooCommerce runtime, whether the POM storefront is active or intentionally dormant, assignment-index freshness, private upload readiness, shared-capacity storage and expired-hold cleanup, and the time of the latest deep diagnostic. Compatibility rows distinguish an extension being detected from its POM integration being loaded. Detection alone is not a compatibility guarantee.
The standard Site Health status page also includes separate POM Product Add-Ons checks for runtime, data integrity, and upload protection. WordPress Site Health information includes the same path-free operational summary.
Understand status levels
- Healthy means the inexpensive runtime and derived-data checks did not find an actionable issue, and the latest saved deep report is healthy when one exists.
- Needs attention means the storefront can normally continue through source-data fallbacks, but an index, optional integration, migration source, unused entity, disabled reference, or translation item needs review.
- Critical means a required runtime is unavailable or the last explicit scan found broken references, invalid definitions, duplicate identities, compatibility-ID problems, ownership problems, an unprotected legacy upload directory, or unavailable private storage used by file fields.
A saved deep report remains visible until another diagnostic is run. Its timestamp is shown in UTC so a support report can be compared across systems.
Run a deep diagnostic
- Select Run deep diagnostic under Protected diagnostic actions.
- Wait for the success notice and review Latest deep diagnostic summary.
- Investigate every non-zero error count before changing live assignments or deleting entities.
- Select Copy redacted support report when you need to share the result with support.
The scan is read-only. It checks stored references and ownership, configuration validity, duplicate UUIDs and compatibility IDs, published groups without an assignment, selected reusable choices that are disabled, assignment-index state, file-storage readiness, translation identity state, and official-extension migration sources. It uses indexed, batched reads with a bounded record limit; a truncated result is marked as needing attention instead of being presented as complete.
The copied JSON excludes customer values, labels, filenames, filesystem paths, site URLs, secrets, and raw request data. Review any diagnostic report according to your store's support and privacy policy before sharing it.
Rebuild caches and derived indexes
Use maintenance only when the panel reports a stale assignment index or compatibility-ID registry, or after support asks you to refresh derived data.
- Select Preview cache and index rebuild.
- Review the new read-only diagnostic summary.
- If the confirmation button appears and the report is still applicable, select Rebuild caches and derived indexes.
- Confirm that Assignment index changes to Valid, then test one affected product.
The preview is short-lived and bound to the current user, site, and diagnostic fingerprint. If source data changes before confirmation, POM rejects the rebuild and asks for another preview. Maintenance rebuilds only caches, the assignment index, and the compatibility-ID registry; it does not edit Product Add-On definitions, assignments, publication state, translations, carts, or orders.
Private storage adapters
The built-in private file store reports its readiness without displaying its directory. A custom object-storage adapter should also implement this health filter so Site Health can distinguish a ready adapter from an unavailable one:
| Filter | Arguments after the initial value | Return value |
|---|---|---|
pom_tweaks_product_addons_file_storage_health |
Context containing blog_id and uploads_enabled |
true when the complete private storage lifecycle is ready, false when unavailable, or null to let POM inspect its local fallback |
The status callback must be cheap and must not disclose bucket names, filesystem paths, credentials, signed URLs, or uploaded object keys.
Developers can lower the deep-scan ceiling with pom_tweaks_product_addons_health_max_records. POM constrains the result between 500 and 50,000 metadata records. Use a lower limit only when a host needs a stricter interactive-operation budget; a truncated scan cannot establish whole-site integrity.
Verify the result
After resolving an issue:
- Run the deep diagnostic again.
- Confirm the expected count is zero or that the remaining warning is understood.
- Open one simple and one variable product that use the affected configuration.
- Add a valid selection to the cart and verify the server-calculated price.
- If files are enabled, test an authorized upload and download without copying a permanent public URL.
Troubleshooting
If POM storefront is dormant, deactivate the official WooCommerce Product Add-Ons extension before using the POM storefront. The panel never changes cutover state itself.
If an index remains stale after maintenance, run another preview. A concurrent configuration publication can intentionally invalidate the previous preview. Product resolution can fall back to source records while the index is unavailable, but repeated staleness should be investigated before broad catalog changes.
If translation orphan or cleanup counts remain non-zero, follow the translation identity migration and cleanup workflow for that site. Site Health reports the condition but does not delete translation strings.
If private uploads are unavailable, confirm that the local private directory is writable or that the storage adapter implements storage, authorized download, deletion, and the health callback. Do not solve the warning by exposing the private directory through a public web URL.
If Shared capacity ledger is unavailable, managed reusable choices fail closed at cart validation and checkout. Confirm the site's database user can create and update the site-scoped Product Add-Ons capacity storage, then reload the enabled tweak so its schema check can run. If Expired-hold cleanup is delayed, expired rows stop counting immediately based on their UTC expiry; cron only performs bounded physical cleanup.
Related guides: Configure groups and reusable choices, Manage reusable-choice availability and shared capacity, and Integrate Product Add-Ons.