More fixes

WordPress plugin install error: "The plugin does not have a valid header"

You upload a plugin zip or click Activate, and WordPress stops with "The package could not be installed. No valid plugins were found." or "The plugin does not have a valid header." The plugin is usually fine. WordPress just cannot find its main file where it expects it. Here is how to tell which case you have, and the fix for each.

What the owner sees

harborbakery.example/wp-admin/plugins.php

What the checks found


  

Find out which case it is (five minutes)

  1. When did it appear? During "Upload Plugin" ("No valid plugins were found"), the zip is packed wrong or is not a plugin. On "Activate", or right after a plugin vanished from the list, the plugin's folder on the server is wrong.
  2. Open the zip on your computer. A good plugin zip holds one folder (for example contact-widget/) and inside it a .php file whose top comment starts with Plugin Name:. If the zip holds another zip, or a folder inside a folder, that is the fault.
  3. Is it really a plugin? A theme zip (it has style.css), a "full package" download from a marketplace (it has documentation and a licence file next to the real zip), or a source download from GitHub (named like plugin-main.zip) all fail this way.
  4. Look on the server. In the host's File Manager or FTP, open wp-content/plugins/. The plugin's folder should contain its main .php file directly, not a second folder of the same name.

The fixes, by case

  1. Zip inside a zip: unzip the download on your computer. Upload the inner zip that is named after the plugin, not the whole package. Marketplaces like CodeCanyon call this the "installable WordPress file only" download.
  2. Folder inside a folder: on the server, move the inner folder's contents up one level (or delete the plugin folder and re-upload a zip that has one folder only). Then go to Plugins and activate it again.
  3. GitHub download: rename the folder from plugin-name-main to plugin-name, zip that folder, and upload the new zip. Better: download the release zip from the plugin's Releases page, which is packed for WordPress.
  4. It is a theme: upload it in Appearance, Themes, Add New, Upload Theme instead.
  5. Main file renamed or broken: if you edited the plugin, the comment block at the top of the main file must still start with /* and contain Plugin Name: Something. A missing line or a file saved with a byte-order mark hides it. Re-download the plugin rather than patching it.
  6. Plugin "deactivated because the plugin file does not exist": the folder was renamed or moved, often by an update that failed halfway. Re-install the plugin from Plugins, Add New; its settings are kept in the database.

What you see, what it means, what it needs

What you seeWhat it meansUsual fix
"No valid plugins were found" on uploadThe zip has no plugin main file at the top levelUpload the inner zip, or re-zip one folder
"The plugin does not have a valid header" on ActivateWordPress looks for the main file in the wrong placeFix the folder-in-folder on the server, then activate
Zip named something-main.zipA GitHub source downloadRename the folder, or use the release zip
Zip contains style.css and screenshotsIt is a themeInstall it under Appearance, Themes
"Plugin file does not exist" after an updateThe plugin folder was renamed or half-replacedRe-install the plugin; settings stay

What not to do

Most cases are one zip opened and one folder moved. If the plugin still will not install, that is what the box below is for. Related: plugin install or update failed, "Add New Plugin" button missing, "file type is not permitted".