When a custom product-category layout works until someone saves the category, compare its stored display key with the theme's matching logic. A case mismatch can select a fallback layout even though the category URL and assigned products have not changed.
The specific compatibility change
WooCommerce 11.2 normalizes custom category display_type values using sanitize_key. A value such as Custom_Grid becomes custom_grid. Code comparing against the old mixed-case value can stop matching after a save. See the official compatibility advisory.
Do not rename the category slug to fix this. Its URL slug, name, taxonomy relationships and display setting are different pieces of data. If an import changed product assignments instead, start with the category-preservation checklist.
Reproduce with one disposable category
- Clone the relevant theme configuration to staging and record the installed WooCommerce version.
- Choose a synthetic category with a known custom layout and two visible products. Record its category ID and display setting.
- Load its public archive and capture the selected template or layout marker.
- Save the category without changing its name, URL slug or product assignments.
- Read the display setting again and compare the renderer's expected key with the stored value.
The important observation is the transition around that save. Comparing two unrelated categories with different templates will not establish a normalization bug.
Before: Record the original setting. Save: Compare normalized value. Reopen: Same option remains selected. Public page: Correct layout and pagination. Explanatory checklist, not a customer test result.
Align registration, persistence and rendering
Use one canonical lowercase key in the code that offers the option, saves it and selects the layout. Inspect custom validation and migration code as well as the final template conditional. Fixing only the public renderer can leave the admin selector displaying no matching option.
If existing categories contain legacy keys, plan an explicit migration with the theme maintainer. First list affected category IDs and current values. Back up the relevant data, test a small staging sample, and confirm that no unrelated term metadata changes. Avoid a blanket database replacement for the word Custom or Grid.
| Check |
Expected result |
| Select custom layout and save |
Saved key matches the registered option |
| Reopen category editor |
Same option is selected |
| Save again without edits |
Key stays unchanged |
| Public archive |
Custom layout renders |
| Normal category |
Default layout remains intact |
Check caches only after the branch matches
A cached archive can keep showing the old layout while the underlying renderer is already fixed. Compare an authorized uncached staging response, then refresh the affected public archive cache. Conversely, clearing a cache cannot fix a conditional that never matches its saved value.
Test desktop and mobile with real category-length titles, pagination and product cards. A corrected template choice can reveal CSS issues that were previously hidden by the fallback.
Give the maintainer a small handoff
Supply the category ID, old and new display keys, renderer location and the before/after save sequence. Keep the public URL stable unless there is a separate reason to change it. HandL WP can trace a custom category template without treating a layout regression as a permalink migration.
References reviewed October 16, 2026. Examples are explanatory, not customer test results.