Troubleshooting

Common issues and how to resolve them.

The site is stuck loading after theme activation

Elementor Pro Theme Builder is hijacking rendering.

1. /wp-admin/plugins.php in a new tab.
2. Deactivate Elementor Pro temporarily.
3. Refresh the front-end.
4. Upload + activate the migrator plugin — trashes the leftover templates.
5. Reactivate Elementor Pro — won't hijack anymore.

The header nav is off-center

Theme.css uses CSS Grid 1fr auto 1fr for perfect centering. If the nav is off-center on live:

1. Autoptimize is serving a stale cache. Admin bar → Autoptimize → Delete Cache.
2. Force a version bump — the theme's ?ver= query on CSS URLs is derived from DANKCAVE_VERSION. Bump it in functions.php + style.css and re-upload.

The footer newsletter form is stacking vertically instead of side-by-side

The theme's CSS targets both MC4WP template variants. If it's stacking:

1. Clear Autoptimize cache.
2. Verify the form HTML is either <div class="dc-mc4wp"> or standard <p>-wrapped fields. Custom form templates the theme doesn't know about won't be styled.

robots.txt still has "Crawl-delay: 30"

There's a physical robots.txt file on the server. WP's robots_txt filter never fires when a physical file exists (Apache/nginx serve it directly).

Fix: Yoast SEO → Tools → File editor → robots.txt → delete the Crawl-delay: 30 line → Save.

The og:image is the small cropped logo, not the branded card

Yoast Premium's modern presenter pipeline doesn't respect the classic wpseo_opengraph_image filter. The theme has a 3-layered fix — verify:

1. Theme version is v0.1.6+.
2. Autoptimize cache cleared.
3. View source → <meta property="og:image"> — should be assets/img/og-share.png.

If still showing the tiny logo, Yoast may have a page-level social image override. Check Yoast SEO panel on the page → Social.

Cart drawer cross-sells show 0 items

Two possibilities:

1. The cart's items have no cross-sell IDs set on the WC products. Assign cross-sells via Products → edit → Linked products → Cross-sells.
2. The fallback query (same-category popular) returned no matches. Confirm the products in the cart have a category assigned, and that category has other in-stock published products.

Search autocomplete returns 0 results

1. Endpoint check: curl 'https://dankcave.com/wp-admin/admin-ajax.php?action=dankcave_search_suggest&q=dab' — should return JSON with html and total.
2. Query too short — the endpoint requires ≥ 2 characters.
3. Autoptimize served stale JS — clear cache.

PDP hover-zoom doesn't activate

1. You're on a touch device. By design, zoom is disabled via @media (hover: none). Mobile gets native pinch-zoom instead.
2. The image element is missing the data-pdp-hero attribute. Verify in DevTools.
3. JS not loading — check browser console for errors.

Age gate keeps re-appearing every visit

Cookie isn't sticking. Check:

1. Browser is in incognito mode → cookies are session-only. Test in a regular window.
2. SameSite policy — the cookie sets SameSite=Lax. If the browser blocks third-party cookies AND the domain is served via a proxy (Cloudflare Workers etc.), the cookie may fail.
3. Verify in DevTools → Application → Cookies → dc_age_confirmed is set to 1.

GA4 events not firing

1. Browser console → window.dataLayer — should be an array. If undefined, GA4 / GTM isn't installed. Configure Site Kit or GTM.
2. Console → trigger the action (add-to-cart, wishlist heart, etc.) → then window.dataLayer.find(x => x.event === 'add_to_cart') — should return the event object.
3. If dataLayer array exists but events aren't there, check for JS errors on the page (Autoptimize's aggressive minification can occasionally break event registration — try disabling Autoptimize's JS optimization temporarily).

Wishlist doesn't persist across sessions

Wishlist is localStorage-only. It persists across browser sessions on the same device + browser, but not across devices and not across incognito → regular window.

Future: sync to user meta for logged-in customers. Phase 3 candidate.

The About page shows placeholder images

The commitment-split and category-showcase patterns pull the top-rated product image from each mapped category. If the categories don't have images (or have no products), the pattern falls back to wc_placeholder_img_src().

Fix: assign products to categories, ensure they have featured images set.

After UpdraftPlus restore, all URLs point to localhost

The restore was of a local backup. Run search-replace:

Tools → Better Search Replace (install the plugin if not present) →

• Search: http://localhost:8090 (or wherever the local was)
• Replace: https://dankcave.com
• Select all tables
• Uncheck "Run as dry run"
• Run.

Then Autoptimize → Delete Cache.

Getting more help

• Filter/hook reference: see README.md → Filters + hooks section
• File map: see README.md → File map section
• Feature-specific: check the relevant page in the sidebar

If none of the above resolve, check the theme's PHP error log at wp-content/debug.log (requires WP_DEBUG_LOG in wp-config.php).