VP Speed - Troubleshooting & FAQ

This reference collects the questions and issues that come up most often with VP Speed, grouped by area. If something doesn't behave as expected, start here — most cases have a one-step fix.

Layout and styling

Part of my site lost its styling after enabling replacement

Your slim bundle is missing a Bootstrap component that your template or content uses. Open the Bootstrap Optimizer, add the missing component (menus usually need dropdown, offcanvas or navbar), save, and clear the cache. If you're unsure which component is involved, temporarily turn off Replace full Bootstrap CSS to confirm that's the cause — the styling will return.

Colors or spacing look slightly off

Make sure CSS variables (root) is selected in Layout & base. Most modern Bootstrap components reference these variables, and leaving them out causes subtle color and spacing issues.

I changed a setting but nothing changed on the front end

Clear the Joomla cache and reload. The compiled CSS updates on save, but cached pages can still reference the old output until the cache is cleared. This is the single most common "it's not working" cause.

Compilation

Saving reports a compilation error

This almost always comes from invalid Custom SCSS — an unclosed brace, a typo in a variable name, or a missing semicolon. Check the SCSS you last edited. Your previous working bundle keeps serving until a valid build succeeds, so the front end stays intact while you fix it.

The compiled file is missing

VP Speed recompiles automatically on the next front-end request if the file is absent — for example after clearing /media. If it doesn't reappear, confirm that /media is writable and re-save the plugin settings.

JavaScript

My delayed scripts disappeared from PageSpeed

That's expected behavior, not a bug. PageSpeed's bot never interacts with the page, so delayed scripts are never requested during the test. Real visitors load them on first interaction. See the JavaScript article for the full explanation.

An interactive element only works after I move the mouse

A script it depends on is being delayed. Add part of that script's URL to Delay exclusions, or add a data-no-delay attribute to its tag. jQuery, Joomla core, WebAuthn login and ES modules are already protected by default.

A console error appeared after enabling delay or defer

An inline script likely runs before a library it needs. Exclude the relevant external script from defer/delay so it loads in its original position. ES modules and importmaps are never deferred or delayed, so module errors point to a different cause.

Browser caching

I enabled caching but PageSpeed still reports no cache policy

Your server is most likely nginx, which bypasses .htaccess. VP Speed's self-check shows a yellow warning right after saving when this happens. Add the caching rule to your nginx configuration or enable static caching in your hosting panel — the Browser Caching article has a copy-paste snippet.

How do I confirm the headers are applied?

Open your browser's network panel, click any CSS or image request, and look for Cache-Control: public, max-age=... in the response headers. If it's present, caching is working; if not, the server isn't applying the rules.

Will a long cache lifetime serve stale files after I update something?

No. Joomla versions static files with a query string, so a changed file gets a new URL and the browser fetches it immediately. The long lifetime only applies while a file is unchanged.

Updates and editions

How do I switch from Free to Pro?

Install the Pro package over the existing plugin — no need to uninstall Free first. Your settings are preserved, and the Pro-only tabs and options appear after installation.

How do updates work?

VP Speed registers with Joomla's update system. New versions appear under System → Update → Extensions with a changelog, and update with one click. No manual re-download is needed.

General

Does VP Speed work with any template?

Yes. It removes the full Bootstrap regardless of how the template loads it — Web Asset Manager, the legacy API, or a hardcoded link. The biggest CSS saving applies to templates that load bootstrap.min.css as a separate file; templates that compile Bootstrap into one combined stylesheet (such as Cassiopeia) still benefit from the JavaScript, icon and caching features.

Does it conflict with other performance plugins?

VP Speed focuses on the source level — compiling Bootstrap, managing how scripts load, and resource hints — rather than full-page caching or HTML/CSS aggregation. It generally complements a caching plugin. If you run another tool that also defers scripts or rewrites the page, enable one such feature at a time to avoid overlap, and test.

Does the Bootstrap compilation slow down my site?

No. Compilation runs once, in the administrator, when you save the settings. Visitors always receive a static, minified, cached CSS file and never trigger a compile.

Where can I get help?

If your question isn't covered here, contact support at support@vpjoomla.com.