Troubleshooting

My CSS styles are broken

Check each potential cause until you find the solution:

1. Force a hard browser reload (bypassing cache). For Chrome: open developer console, right-click reload, select "Clear cache and reload".

2. Inspect the styles.css HTTP request in your browser's developer tools (Networking tab).

   • If 200 or 50x response: Check the response preview for potential PHP errors.
   • If 404 response: Verify production mode (`bin/magento deploy:mode:show`) and successful static content deployment (`bin/magento setup:static-content:deploy`).

3. Check TailwindCSS compilation. If using `npm run watch`, try `npm run build` and review its output for errors.

4. If `styles.css` loads but styles are still broken, the issue is likely HTML/CSS related. Check the browser console for errors/warnings and use the DOM inspector's Styles tab for debugging.

Compilation from source: LESS file is empty: …/email-fonts.less

When running static content deploy, you might see this error:

Compilation from source: LESS file is empty: frontend/Hyva/reset/xx_XX/css/email-fonts.less

This warning is safe to ignore; it does not abort compilation.

To resolve this, upgrade `hyva-themes/magento2-email-module` to version 1.0.4 or later.

“Incorrect CAPTCHA” error messages

Hyvä does not support legacy Magento Captcha or reCAPTCHA V1 (see Feature Matrix and Getting Started).

Disable the legacy Captcha, which is often enabled by default:

bin/magento config:set customer/captcha/enable 0

tailwindcss: Permission Denied Error

This error often occurs after macOS Sonoma/Xcode upgrades, usually due to an outdated npm installation.

Solution:

The simplest fix is to remove the `node_modules` folder and reinstall packages.

Steps:

1. Navigate to your project theme directory.
2. Run these commands:
   rm -rf node_modules
   npm install
   

This removes the old `node_modules` and reinstalls packages, ensuring compatibility.

Child theme throws exception "Overriding view file '...xml' does not match to any of the files."

This error occurs after creating and loading a child theme.

Exception #0 (LogicException): Overriding view file 'vendor/hyva-themes/magento2-reset-theme/.../layout/override/base/....xml' does not match to any of the files.

The exact XML file path may vary. If this happens, ensure the `Hyva_Theme` module is active.

bin/magento module:status Hyva_Theme

If the output shows:

Hyva_Theme : Module is disabled

Then, enable the module and run `setup:upgrade`.

bin/magento module:enable Hyva_Theme
bin/magento setup:upgrade

Missing Page Header Styling

Steps:

1. Verify TailwindCSS Purge Settings:
   Ensure purge settings are correctly configured. This is a common first check.

2. Check for `esi` Tags in Header:
   If only the header is broken, `esi` tags might be the cause, indicating Varnish is enabled in Magento 2 admin.

3. Handle Varnish in Local Development:
   Disable Varnish for local development unless needed. If enabled, ensure it's correctly configured to avoid styling conflicts.

4. Disable Varnish for Local Development:

5. a. Go to `Stores → Configuration → Advanced → System → Full Page Cache`.
6. b. Set Caching Application to Built-in Cache.

How to fix "Invalid form key" issue with enabled Cloudflare Rocket Loader?

Hyvä releases up to 1.2.3 are incompatible with Cloudflare Rocket Loader.

As per Cloudflare docs, add `data-cfasync="false"` to relevant JavaScript tags:

<script data-cfasync="false" src="/javascript.js"></script>

Visitors see the wrong store view and are unable to switch

This occurs when requests have a `store` cookie but no `X-Magento-Vary` cookie, and the default store URL's FPC record is expired. This can happen if a visitor's session times out after selecting a non-default store view.

Varnish caches pages using the `X-Magento-Vary` cookie, while Magento uses the `store` cookie for store view rendering. For the default store view (guest group), neither cookie is set. If a request has a `store` cookie for a non-default view but no `X-Magento-Vary` cookie, Varnish may incorrectly cache it as the default store view page.

Adjusting the default Varnish configuration can fix this. Replace:

sub vcl_hash {
    if (req.http.cookie ~ "X-Magento-Vary=") {
        hash_data(regsub(req.http.cookie, "^.*?X-Magento-Vary=([^;]+);*.*$", "\1"));
    }

with the following:

sub vcl_hash {
    if (req.http.cookie ~ "X-Magento-Vary=") {
            hash_data(regsub(req.http.cookie, "^.*?X-Magento-Vary=([^;]+);*.*$", "\1"));
        } else {
            # If there is no 'X-Magento-Vary' cookie set, then there should also be no 'store' cookie
            # This check prevents requests with illegal cookie state from polluting the cache for default store view:
            if (req.http.cookie ~ "store=") {
                hash_data(regsub(req.http.cookie, "^.*?store=([^;]+);*.*$", "\1"));
            }
        }

(Solution courtesy of Maximilian Fickers from basecom.de)