WordPress Debug Notice: Notice: add_submenu_page was called incorrectly

In newer WordPress versions there might be introduced incompatibility with older plugins. If you have debugging enabled by default, these notices might fill-up your PHP error logs and give you certain level of anxiety and discomfort.

How To Fix: WordPress Debug Notice: Notice: add_submenu_page was called incorrectly

WordPress Logo 1920x780 White Background

WordPress

Your PHP error log might look something like this:

PHP Notice: add_submenu_page was called incorrectly. The seventh parameter passed to add_submenu_page() should be an integer representing menu position.

We’ll provide real-world examples from an older plugins and solutions how to easily fix them.

Problem with this generic notice (technically speaking it is not a critical error because PHP and WordPress will continue to normally run!) is that it doesn’t reveal to the end-user (which is you) exact line of code or plugin name that causes it. So, the first step we have to do, even on production sites unless you have a 1:1 mirror copy on a development/test server, is to determine which plugin is causing it by disabling them gradually.

STEP 1: Identify Problem Plugin

WordPress > Admin Dashboard > Plugins

The quickest way to do this is to bulk deactivate top half (50%) of the plugins you use, and leave bottom half active. Then simply reload admin page (F5) and check error logs to see if it disappeared. If the problem still exists, plugin is located at the bottom half in WordPress Admin Menu > Plugins table.

Logically, reactivate top half in the table, and now deactivate bottom half of the plugins. Now, you can recursively activate (enable) one-by-one (or quarter of the remaining plugins) and repeat page refresh and error logs checks until you find the culprit!

Once the problematic plugin is identified, you can report a problem to the developer in the respective WordPress Plugins support forum section, but most likely it is an old and abandoned plugin no longer actively maintained.

In that case, you can either try to find a substitute plugin that still has active support, newer code base and features, and is certified to be compatible with latest WordPress core version.

If you cannot simply replace it, then you should try to fix the problem by yourself. Here’s one example how we did it.

STEP 2: Fix Problem Plugin

First, the above reported notice (bug) in the error log file may be misleading because the actual function name is completely different! What we mean by this is that function name that adds plugin’s menu pages in Admin Dashboard settings section is created by a plugin developer, so in order to find it, you have to look for underlying WordPress core function that it actually calls! And, as if the problem isn’t already complex enough for novice users and administrators, problem doesn’t stop there because there are several different WordPress functions used for menu pages as demonstrated below.

Look at following examples to get a better understanding what we mean by this and get some ideas:

Example #1

Wrong variable
$some_variable = add_management_page('Key', 'Key', 'read', 'key', array($this, 'admin_page'), '')
Fixed variable
$some_variable = add_management_page('Key', 'Key', 'read', 'key', array($this, 'admin_page'), null)

💡 We replaced last parameter  ‘ ‘  (empty string) with null parameter above and that fixed the problem.

👉 The key string you should search in plugin files is the string add_management_page function name which will hopefully lead you to solution. Remember, it may be buried under many subfolder, nested functions and classes, so use search within files feature in code editing tools.

Example #2

Wrong function
add_options_page('Sitemap', 'Google XML Sitemap', 'administrator', __FILE__, 'gsg_csitemap_settings_page', '', __FILE__);
Fixed function
add_options_page('Sitemap', 'Google XML Sitemap', 'administrator', __FILE__, 'gsg_csitemap_settings_page');

💡 We removed 6th and 7th parameters above (parameter places are separated / counted by comma symbols) because (A) 7th parameter is excessive in this function now and (B) 6th parameter can be either set to null or omitted (it is assumed to be null in WordPress’s core function itself).

👉 The key string you should search in plugin files is the string add_options_page function name which will hopefully lead you to solution. Remember, it may be buried under sub-sub-folders, nested functions and classes, so use search within files feature in code editing tools.

Search Keywords / Functions
  • add_options_page
  • add_management_page
  • add_submenu_page

This is a summarized list of common WordPress core functions that may cause these notices and are worth checking in your plugins.

How To Access / Search Inside WordPress Plugins Files and Folders

cPanel Hosting

Login into your cPanel and access File Manager icon from your cPanel Dashboard that looks something like this:

cPanel File Manager

cPanel File Manager

Once cPanel File Manager app loads into your web browser (Chrome, Firefox, Opera, Vivaldi etc.), use built-in search feature. Please note that you will have to scroll through the list with your mouse using drag movement, because the popup window is a bit buggy currently. Also, search is limited to 250 results, so if you have a lot of plugins, we suggest that you navigate to the problematic plugin first and then set search location to current folder using drop-down selector in the top right corner. This will speed-up search process!

cPanel File Manager - How To Search Within Files and Code

cPanel File Manager – How To Search Within Files and Code

Finally, navigate to the located file that contains the problematic code and use cPanel File Manager code editor feature to edit it:

cPanel File Manager - How To Edit Code Files on Server 1

cPanel File Manager – How To Edit Code Files on Server 1

Fix the problematic line and hit Save:

cPanel File Manager - How To Edit Code Files on Server 2

cPanel File Manager – How To Edit Code Files on Server 2

Built-In WordPress File Editor

WordPress Admin Dashboard > Plugins > Plugin Editor

You can also use built-in file editor in WordPress for quick fixes like this, once you know where and which file and code line you need to fix. This is a least-popular option (at least, in our case) which we practically never use, but it is there for your convenience.

WordPress Admin Dashboard - Plugins File Editor - How To Edit Code Files on Server

WordPress Admin Dashboard – Plugins File Editor – How To Edit Code Files on Server

Self-Hosted / VPS / Dedi Servers

Connect to your WordPress server via FTP or SFTP application, then locate your public www or public_html directory, navigate down to wp-content/plugins folder and look for the name of your plugin that was identified to cause notices. We suggest that you download entire directory to your local computer first. Next, use Notepad++ or similar code editor of choice and search with files for above mentioned menu functions to locate problematic lines in the code. Fix the code, save the files and then re-upload fixed plugin back via FTP / SFTP to the server.

WordPress Admin Dashboard – Plugin Menu Item Functions – Parameters Explained

WordPress Plugin Debugging - add_submenu_page was called incorrectly example

WordPress Plugin Debugging – add_submenu_page was called incorrectly example

WordPress Menu Functions: add_options_page() / add_management_page()

Admin Dashboard > Settings Menu
add_options_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', int $position = null )

Admin Dashboard > Tools Menu
add_management_page( string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', int $position = null )

1st parameter in above functions defines HTML page’s title when you visit your plugin’s settings page in the Admin Dashboard. It’s simple and not critical.

2nd parameter defines Menu Item title in the Admin Dashboard Settings or custom plugin’s settings page. It is also not critical.

3rd parameter in above examples is very important (‘read’ or ‘administrator’ or ‘manage_options’ are common values), because it defines who can access and change plugin’s pages! Make sure you do not mess around the position of this parameter while fixing the problem.

4th parameter allows developers to define custom page slug, that is, portion of the value in the URL of the admin dashboard plugin’s settings page in question. String must be url encoded and avoid spaces or special characters, although all moderns servers and browsers will easily deal with them, anyway.

5th parameter is critical because it calls a function or method and you must be careful not to change it! Plugin will stop properly working e.g. you will not be able to access plugin’s settings page if you break it! In our above example ‘gsg_csitemap_settings_page’ parameter actually calls gsg_csitemap_settings_page() plugin function which inserts plugin’s settings page in Admin Dashboard > Settings menu.

6th parameter is what was actually causing the original problem and that’s what we need to fix. Instead of an empty string ” we must either pass integer (whole number e.g. 1, 2, 3, etc. without quotes of any kind) or null or simply omit it!

7th parameter does not exist e.g. we may pass it but underlying WordPress core function will ignore it e.g. not use it at all! That is why we removed it altogether in our fix above.

WordPress SubMenu Function: add_submenu_page()

This function is little different than above two and it actually accepts 7 parameters in total.

add_submenu_page( string $parent_slug, string $page_title, string $menu_title, string $capability, string $menu_slug, callable $function = '', int $position = null )

1st parameter allows developers to define custom parent slug in the multi-submenus structure

2nd parameter defines HTML page’s title when you visit your plugin’s settings page in the Admin Dashboard. It’s simple and not critical.

3rd parameter defines Menu Item title in the Admin Dashboard Settings or custom plugin’s settings page. It is also not critical.

4th parameter is very important (‘read’ or ‘administrator’ or ‘manage_options’ are common values), because it defines who can access and change plugin’s pages! Make sure you do not mess around the position of this parameter while fixing the problem.

5th parameter allows developers to define custom page slug, that is, portion of the value in the URL of the admin dashboard plugin’s settings page in question. String must be url encoded and avoid spaces or special characters, although all moderns servers and browsers will easily deal with them, anyway.

6th parameter is critical because it calls a function or method and you must be careful not to change it! Plugin will stop properly working e.g. you will not be able to access plugin’s settings page if you break it! In our above example ‘gsg_csitemap_settings_page’ parameter actually calls gsg_csitemap_settings_page() plugin function which inserts plugin’s settings page in Admin Dashboard > Settings menu.

7th parameter is what was actually causing the original problem and that’s what we need to fix. Instead of an empty string ” we must either pass integer (whole number e.g. 1, 2, 3, etc. without quotes of any kind) or null or simply omit it!

Comments


Post A Comment

I have read and consent to Privacy Policy and Terms and Conditions