How to fix the ‘The plugin does not have a valid header’ error when activating a WordPress plugin

You want to extend WordPress’ functionality and decided to download some plugins found in the Official WordPress Plugin repository. After searching the repo, you’ve found two plugins that accomplishes the tasks you needed to implement in your blog. Downloading the plugins gives you two ZIP files that when double-clicked, shows you the contents in the following format:

plugin-a.zip

plugin-a-folder
---- plugin-a-main-file.php
---- plugin-a-readme.txt

plugin-b.zip

plugin-b-folder
---- plugin-b-subfolder
-------- plugin-b-main-file.php
-------- plugin-b-readme.txt

There are two ways to install a plugin. Option 1 is to unzip the file and upload the contents to wordpress_root/wp-content/plugins/ directory. Option 2 is to use the Add New -> Upload option found in the left panel bar of the administrative page of WordPress. Let’s assume the two plugins went through the two installation options.

Installing ‘plugin-a.zip’ using Option 1

  1. Unzip the file
  2. Upload the contents to wordpress_root/wp-content/plugins/
  3. Login as admin and go to Plugins -> Installed.
  4. Locate plugin and click Activate link.
  5. Result:
    Plugin activated.

Installing ‘plugin-a.zip’ using Option 2

  1. Login as admin and go to Plugins -> Add New -> Upload
  2. Locate the file plugin-a.zip by clicking the Browse button.
  3. Click Install Now button.
  4. Result:
    Unpacking the package?
    Installing the plugin?
    Plugin installed successfully.
  5. Click Activate Plugin link.
  6. Result:
    Plugin activated.

Installing ‘plugin-b.zip’ using Option 1

  1. Unzip the file
  2. Upload the contents to wordpress_root/wp-content/plugins/
  3. Login as admin and go to Plugins -> Installed.
  4. Locate plugin and click Activate link.
  5. Error: Plugin does not exists in the list.

Installing ‘plugin-b.zip’ using Option 2

  1. Login as admin and go to Plugins -> Add New -> Upload
  2. Locate the file plugin-b.zip by clicking the Browse button.
  3. Click Install Now button.
  4. Result:
    Unpacking the package?
    Installing the plugin?
    Plugin installed successfully.
  5. Click Activate Plugin link.
  6. WordPress ? Error
    The plugin does not have a valid header.

Based on our testing, plugin-b.zip seems to fail on both methods of installation. To find out what is causing the error, we have to understand how the plugin installation works. Upon checking the core files I found this excerpt in get_plugins() function:

* WordPress only supports plugin files in the base plugins directory
* (wp-content/plugins) and in one directory above the plugins directory
* (wp-content/plugins/my-plugin). The file it looks for has the plugin data and
* must be found in those two locations. It is recommended that do keep your
* plugin files in directories.

The plugin data that the function is looking for can be found below:

<?php
/*
Plugin Name: Name Of The Plugin
Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
Description: A brief description of the Plugin.
Version: The Plugin's Version Number, e.g.: 1.0
Author: Name Of The Plugin Author
Author URI: http://URI_Of_The_Plugin_Author
License: A "Slug" license name e.g. GPL2
*/
?>

So in order to properly install and activate a plugin, the following two conditions must be satisfied:

  • that a plugin main file (.php) must be placed in plugins root folder or in first-level subdirectory within plugins folder
  • and it should contain the necessary plugin data for identification/validation purposes

In the case of plugin-b.zip, although the main PHP file contains the needed plugin data, the validate_plugin() function returned an error since neither the file can be found or check if it contains the plugin data because it is placed in the second level subdirectory, a directory location in which the function is not designed to scan the content.

To fix the plugin-b.zip file, it needs to have the following content structure:

plugin-b.zip

plugin-b-folder
---- plugin-b-main-file.php
---- plugin-b-readme.txt

I hope this post will enlighten WordPress users who wants to maximize their blog’s potential πŸ™‚

About the author

Richard Feraro is a Magento Enterprise Certified developer from Manila, Philippines with 14 years of solid open-source development experience using Linux, Apache, MySQL & PHP.

Leave a Reply

  1. Hi Richard,great site.Im using wordpress and I dont know where to find the folder wherein I should change the code as you explained.You see Im also getting the error:he plugin does not have a valid header’.Sometimes I wish there were some affordable outsourcing services to fix and customize WordPress blogs because Im a writer and more on marketing and strategic issues than coding.Please help.Thanks

    • Hello Sarah, thanks for checking out my blog.

      Regarding your inquiry, what is the plugin’s name that you’re having trouble with?

  2. Thanks Richard, I moved the plugin-appname.php and appname-readme.txt to the first level folder (the plugin folder root) and the plugin activated. I appreciate your help.

  3. hi Richard,

    i was hopping to solve this for classipress plugin but it doesnt really work.
    after i unzip the folder there is no file called “classipress.php” , so i dont know which one is the main file ? i tried renaming index.php to clasipress.php and copy it to the root plugin folder …

    i am stuck now and i really need this

    thanks

  4. This is wearing me out. I get one plugin installed and another one self destructs! I’ve updated the version numbers and no luck. Can’t we just disable whatever is checking for the version numbers and carry on with our work? It’s driving me crazy. Who cares what version it’s good up to.

    • There’s a good reason why a version check is necessary for the plugin. It keeps our WP instance from breaking due to incompatible version which in your case is possibly the reason why the two plugin didn’t work well together.

  5. Hi Richard

    I understand what you’re saying here… to a degree.

    How do I alter the zip file? If I double-click it, the file is opened by WinRAR. Do I need to amend one of the files within the zip file?

    Regards

    Ian

    • Just unzip it then move the files to the first subdirectory. After that, you may upload it or zip it again for installation to your WP instance.

  6. “that a plugin main file (.php) must be placed in plugins root folder or in first-level subdirectory within plugins folder” … This worked for me .. thanks

  7. Everything is perfect from my side, placing plugin in one level directory but also it showing that “The plugin does not have a valid header.”
    wordpress version 3.0

  8. What do i have to move?
    β€œThe plugin does not have a valid header.”
    Fatal error: Call to undefined function dockgalleryfx_echo_embed_code() on line 12

    Welcome to jsnsdr

  9. Mabuhay Richard –

    Glad to have found your site while searching the net. As a non-techie guy and with very basic knowledge of PHP and MySQL (mainly simple installing of sites and databases), I hope to learn more from you here.

    Used to live in Makati at the Twin towers when working with Ayala Corp. Now in Singapore and starting my full time online presence. A long way to go but taking it in my stride and planning outsourcing work mainly on graphics and sites as well as promo activities through various operatives in Fiverr and others.

    This header fixing lesson is very helpful and appreciate very much.

    All the best and take care.

    • Hello Hugo,

      I am glad you found the article to be useful πŸ™‚ I hope you visit once in a while in the site. Read through the comments too. Most of the visitors here find them useful in their job.

      Regards πŸ™‚

  10. Hi Richard,

    I am sure all your site’s visitors would certainly benefit from your guidance and tutorials…judging from the compliments from them.
    I am happy for you that your effort has reaped the rewards in terms of a great sense of satisfaction.

    Rest assured that I have bookmarked your site and you bet I will be here whenever I can to continue learning from you and will make good use of what I have learned here.

    Once again, thank you and my best regards to you and your loved ones.

  11. Richard,

    Don’t know what to say about how well you explained this plugin error stuff ” the plugin does not have a valid header”.

    I don’t think there are many folks out there with the organizational and teaching skills you have not to mention the generosity in putting this answer together. WOW!
    Finally I was able to get the “mediaplayer-5.9-viral” activated thanks to your identification/validation php data example.

    For a dummie-newbie like me, your explanation came like a God send,
    thank you so much pal and my sincere gratitude.

  12. HI,
    Thank you for the post. I’m having the Β«The plugin does not have a valid header.Β» problem. At first I could install plugins but now it doesn’t let me or upgrade the ones I have (It says they are upgraded but they aren’t). I checked the folder plugins and they had the files as you indicate. The wp_plugins folder has now the 777 permission but I still can’t do anything. And one more: I could only upgrade wp to 3.4.2 using the simple scripts.
    Do you have any ideas? I’ve searched wp foruns and google it but no solution worked.

  13. This is helpful, but I’m really puzzled. Our blog plugins — ALL of them — are being auto deactivated. They seem to work for about an hour, then when I login, I receive a page summarizing multiple errors – one for each plugin stating “The plugin does not have a valid header.”

    Have you encountered anything like this before? What suggestions do you have? Should we follow your recommendations above for each plugin? I’ve never had a problem like this on any WP blog I’ve set up and it’s got me a bit rattled. Thanks for your insights.