Troubleshooting JavaScript Problems

There are two reasons you found this article. I will handle both here.

1. You have a general issue with JavaScript or jQuery.
2. You see a warning in your WordPress Dashboard that our Advanced Ads plugin might not work properly due to JavaScript issues. This can also apply to other WordPress plugins looking odd or not working as expected in the backend.

Identify JavaScript problems

Test another browser

When something is not working in the WordPress dashboard, it could relate to a browser setting. So before getting into more technical troubleshooting, you might want to check if the same issue happens in another browser. If not, then these are common causes:

• You are using an ad blocker – disable it
• You are logged-in in one browser, but not another – clear your cache in browser browsers and check if you have options enabled that show different code to logged-in users than to others

Identify the cause

When I suspect a JavaScript issue in the frontend or backend of a (WordPress) website, I open the debug console in the browser. On Chrome, you can do that using alt + cmd + J on the keyboard on Mac or Control + Shift + J on Windows. Then navigate to the “Console” tab.

Reload the page while keeping the debug tools open to make sure that errors are caught. Now, anything that shows up in red is an error that could potentially break something on your site.

Next to the error message, you might find a link to the script causing the warning and a reference to the line in the code.

Hover over that link to see where the file that contains the issue is located. In the WordPress dashboard, there is a high chance that it will lead you to a plugin or theme. Use that information for the next step.

Test another plugin or theme

Once you identified the script related to the issue, you can disable the plugin or theme related to it. As we describe under How to check for plugin and theme conflicts, you can use the Health Check plugin to do that without actually changing your site for other users. While I suggest you still do that in a test environment, it would also work if your site is live.

When you disabled the plugin or switched to another theme and the issue is gone, and the features that didn’t work before are working now, then you can implement a solution if you are a developer. The tips below might also help.

If you are not a developer, then you have already done the basic troubleshooting for someone else to take over. Just let your main developer take over from here, or if a third-party plugin or theme causes the issue, let their authors know how they can reproduce the problem.

Troubleshooting tips for developers

If you know your way around code and want to find out which theme or plugin causes the issue without disabling them, you should enable SCRIPT_DEBUG in your wp-config.php. Just add the following line in the appropriate place. If you don’t know what I mean by “appropriate place”, then you might want to let someone with the debug experience take over.

define('SCRIPT_DEBUG', true);Code language: JavaScript (javascript)

This allows you to see all included files in your page’s source code in the WordPress dashboard instead of a combined version for core files.

Fixing jQuery is not defined

The following error is quite common and, in general, causing many JavaScript- and jQuery-based functions to break.

Uncaught ReferenceError: jQuery is not definedCode language: JavaScript (javascript)

jQuery is a JavaScript library. A lot of themes and plugins rely on it to being enabled. WordPress core comes with the needed files, but they might either be disabled or loaded after some other code required it.

$ is not defined

$ is an alias for jQuery in code. In some cases, it can just help to replace $ with jQuery to solve the issue.

In most other cases, $ is not defined is a variant of jQuery is not defined, and the suggestions below apply the same way.

Disable script optimization

The most common cause of this error is using a plugin or service that minifies JavaScript files and/or moves them to the page’s footer.

Among such plugins are WP Rocket or Autoptimize. Services that could do this are CloudFlare or some features in dedicated WordPress hosting.

I would suggest identifying the usage of such plugin or services on your site and disable the feature that manipulates script files for testing.

Most plugins and services with the mentioned optimization feature have dedicated troubleshooting sites with suggestions on how to resolve the issue without touching the compromising code. Here, you can find more information about the needed settings in WP Rocket.

If you are technical, you might want to look at the next step and adjust the code that is not working well with delayed jQuery.

Look for the causing script

Open the developer console to find the error highlighted in red.

After the error, in our example ?p=1:56, you find the code mentioned trying to call jQuery. Click on the link to jump to the line in the frontend code or the script causing it.

Rewrite jQuery code to wait

If you are the developer of the code that causes the issue, you have two options to fix it:

• Configure the script optimization plugin so that it also includes the code that needs jQuery to being optimized and loaded later
• Rewrite your code when changing the position is not possible.

The following is a solution for the latter, when you cannot change the code’s position but can still make adjustments. It uses a function we built for Advanced Ads to make our features work with delayed jQuery.

My example changes the color of h1 headlines into red. Instead of calling it like this

<script>jQuery('h1').css('color', 'red');</script>Code language: HTML, XML (xml)

we are using the advanced_ads_ready function to wait until the site is loaded.

<script>( window.advanced_ads_ready ).call( null, function() { jQuery('h1').css('color', 'red'); })</script>Code language: HTML, XML (xml)

Please note that this function is only available as long as Advanced Ads is activated.

Solutions that don’t work

I have seen publishers trying to solve jQuery is not defined with copy&paste code from the internet. Especially when the suggestions are not coming from the context of using WordPress, they might cause more problems.

Developers might know jQuery(document).ready(). This helps you to wait for the whole site to load before applying code. However, it does not help our specific scenario, since it also needs the jQuery file to being available.

Some sources suggest to loading jQuery again by adding a line like the following into your website’s code.

<script type="text/javascript" src="http://code.jquery.com/jquery-2.2.4.min.js"></script>Code language: HTML, XML (xml)

If WordPress takes care of loading the jQuery file, as it should (!), adding it a second time will break code depending on it.

See the next section about finding out whether your site already uses multiple files that load the jQuery library.

Fixing duplicate jQuery files

A common issue that could break your site’s scripts is the inclusion of the jQuery library files more than one time.

There are plugins dedicated to adding jQuery to your site, or (older) plugins and themes might still load their jQuery version. In the latter case, you should disable such plugins or let their developers know that they need to use the files delivered with WordPress code.

An indicator of this problem is the critical warning Uncaught ReferenceError: jQuery is not defined in the browser’s developer console.

If the suggestions above don’t help you to fix it, you can look for multiple jQuery files. Note that I am referring to the main jQuery library files, not extensions.

1. Disable any features in a plugin or service that minifies and combines JavaScript files
2. open the developer tools in your browser and select the Network tab
3. filter the list by selecting “JS” and entering “jquery” in the filter field
4. reload the page
5. in the list that shows up (see the screenshot below), look for jquery.min.js or jquery.js – there should only be one of them, optimally located in /wp-includes/js/jquery/jquery.min.js, which is the file coming with WordPress core

When you see more than one jQuery core file, then look at their URLs. This should help you identify where the additional jQuery file is coming from.

To fix the issue yourself, you can use wp_dequeue_script() on the duplicate or disable the plugin adding that file.

Fixing layout issues in WP Admin

When you reached this page through the WordPress dashboard, there is likely a problem with buttons or layouts not looking or working correctly.

WordPress 5.6 caused this warning to pop up more often. Please update to Advanced Ads 1.22.0 where we fixed the issue.

It is likely that with this error, options just look odd but should work properly. For example, select buttons might look like this

Instead of

Reason A: multiple calls to jQuery

The reason for such issues is likely the double inclusion of the jQuery library or some sub-libraries.

WordPress itself includes the jQuery library already. Unfortunately, some themes or plugins also load it. Loading it twice is likely to break any code that relies on it.

For example, this might be the order of jQuery files being included in the header of the site:

1. jquery.js //wordpress core
2. jquery-migrate.min.js //wordpress core
3. jquery/ui/core.min.js //wordpress core
4. jquery/ui/widget.min.js //wordpress core
5. jquery-1.12.1.js // CUSTOM JS, loaded by plugin or theme. Overrides 1, 2, 3, 4
6. jquery/ui/accordion.min.js //wordpress core. Error, 3 and 4 not found
7. jquery/ui/button.min.js //wordpress core. Error, 3 and 4 not found
8. jquery/ui/tooltip.min.js //wordpress core. Error, 3 and 4 not found

Number 5 is a duplicate inclusion of the jQuery library, which causes issues with the following library files.

See “Fixing duplicate jQuery files” above for finding and removing duplicate jQuery core files.

Reason B: bootstrap.js

Similar to jQuery.js, your theme or another plugin might also use the bootstrap.js library. While using your copy of the jQuery library is a sin, bootstrap.js is not included in the WordPress core. It just conflicts with some scripts in Advanced Ads. It is not much you can do about it. In the best case, the backend still works despite the layout issue.