The feature works in staging or when optimisation is disabled, but production reports an error inside a one-line minified bundle. The original code may rely on execution order, contain syntax the optimiser mishandles or be combined with a stale dependency.
Restore the critical user journey first, then reproduce the smallest failing transformation.
Capture the public failure precisely
Test as a logged-out visitor and record the page, action, browser, error text, script URL and line/column. Save the stack trace and network response status.
Check whether the error occurs on first load, after navigating between pages or only after opening a component. A cached visitor can receive a different bundle from a fresh session.
If forms or checkout are broken, use the optimiser’s supported bypass or disable the specific JavaScript transformation while diagnosing. Keep the previous configuration documented.
Confirm which optimisation stage causes it
In staging, test these states separately:
- original individual files;
- minified but not combined;
- combined without minification;
- delayed or deferred after minification;
- the complete production configuration.
The first state where the error appears narrows the cause. Do not toggle minify, combine and delay together and call the group “the optimiser.”
Keep theme, plugin versions and page content aligned with production so the comparison is meaningful.
Map the bundle back to source files
Use the optimiser’s manifest, source comment or debug mode to list files inside the bundle. Search original sources for the failing function or a nearby string.
If a legitimate source map is produced, browser developer tools can map the stack to the original line. Do not expose private source maps publicly merely for easier diagnosis; configure access according to the project’s security policy.
Compare the response content with the current manifest. A CDN may serve an old bundle under a reused URL.
Look for execution-order dependencies
Combining files can change order when dependencies were expressed only through separate script tags. One plugin might expect jQuery or a global configuration object to exist first.
WordPress scripts should register dependencies explicitly. Custom code can use:
wp_enqueue_script(
'site-checkout',
get_stylesheet_directory_uri() . '/js/checkout.js',
array('jquery', 'wc-checkout'),
'1.4.0',
true
);Use real verified handles. Do not copy this checkout example into a site that registers different dependencies.
Inline “before” and “after” data must remain beside the correct handle. Moving it into an aggregate can invert the required sequence.
Check syntax and unsafe transformations
Older minifiers can fail on newer JavaScript syntax, regular expressions or code that depends on function/class names. Third-party scripts may already be minified and should not be processed again.
Exclude the smallest proven file from minification while preserving its normal load order. If you own the source, update the build tool or correct unsafe code rather than maintaining a permanent broad exclusion.
Never hand-edit the generated one-line bundle; it will be regenerated and is not the source of truth.
Eliminate stale cache combinations
Version bundle URLs when their content changes. Purge the affected HTML and exact asset URL through supported controls, then test a fresh session.
A new HTML document referencing an old deleted bundle produces a 404; old HTML referencing a newly overwritten bundle can create incompatible code. Atomic deployment or content-hashed filenames avoid that mismatch.
Do not flush every production cache repeatedly. It increases origin load and makes the failure harder to reproduce.
Run regression checks
After the narrow repair, test navigation, forms, consent, sliders and authorised checkout flows. Review the console on several templates and browsers.
Confirm the production asset is minified or excluded exactly as intended, loads once and remains stable across a second cached visit. Record the responsible file and reason for exclusion so a future plugin update prompts review.
Request an assessment when the bundle manifest is unavailable, different cache layers serve inconsistent code or payment/form dependencies are involved. Share the public error evidence first and arrange secure access only after scope is agreed.