Fixing the Plugin Does Not Have a Valid Header Error
The file WordPress was asked to activate exists, but nothing in its first 8 KB says Plugin Name. That narrows it to a damaged header or an unreadable file; a missing file, a nested zip and a stray folder each produce a different message, or none.
The file exists, WordPress read it, and nothing in its first 8 KB declares Plugin Name:. "The plugin does not have a valid header." is what validate_plugin() returns on activation when the file it was given is present but is not in the list of recognised plugins. That rules out several things people assume: a file that is missing produces "Plugin file does not exist", a bad zip produces "No valid plugins were found", and a stray folder produces nothing at all. What is left is a header that no longer parses, or a file the web server cannot read.
What the check actually does
For each folder in wp-content/plugins/, WordPress reads the first 8 KB of every .php file at that folder's top level and looks for a line containing Plugin Name:. The parser is forgiving about how the line is commented:
<?php
/**
* Plugin Name: Example Plugin
* Version: 1.2.0
*/
A // Plugin Name: line, a # Plugin Name: line, or the same text on the opening <?php line all match. A byte order mark at the start of the file does not stop the match either. What does break it: the line is gone, it is inside a string, it sits past the first 8 KB because a large comment or code block precedes it, or the file cannot be opened.
Which message you are actually seeing
| Message | Where it comes from | Cause |
|---|---|---|
| The plugin does not have a valid header. | Activation of an existing file | Header line damaged or past 8 KB; file unreadable |
| Plugin file does not exist. | Activation, or the next admin load after a plugin's file vanished | Main file renamed, moved or deleted; a failed update left the folder empty |
| The package could not be installed. No valid plugins were found. | Upload installer | Bundle instead of plugin zip; plugin nested one folder down; a theme uploaded as a plugin |
| Nothing — the plugin is simply not listed | Plugins screen | A folder with no header file at its top level is skipped silently |
Match your message to the row before fixing anything. Three of the four are not a header problem, and two of them are covered elsewhere: the nested or bundled zip is the plugin counterpart of the theme missing style.css, and the empty folder after a failed update comes from the same causes as could not create directory.
Cause 1: an edited header
Someone opened the main file to change the version or the description and left the comment block in a state the parser does not read: the Plugin Name: line deleted, the colon removed, the line moved below a large block of code, or the file saved as a single long line. Restore the line near the top of the file, keep the colon, and keep the whole header comment within the first 8 KB. A header that has been pushed down by a licence block or a configuration array pasted above it is the subtle version.
Cause 2: the file is not readable
A .php file the web server cannot open is scanned as if it were empty. After a deploy, a restore, or a manual upload as a different user, the main file may be owned by an account PHP cannot read from, or have a mode of 600. Compare it to its neighbours:
ls -l wp-content/plugins/example/
Files should be 644 and owned by the same user as the rest of the folder. Fixing ownership is the same procedure as for any other could not create directory case, and chmod 777 is as wrong here as it is there.
Cause 3: a stub left by a build or deploy
Build tools and deploy scripts sometimes replace the main file with a placeholder — an empty file, a file containing only <?php, or a compiled bundle whose header comment was stripped by a minifier. The file exists, so WordPress reports the header rather than a missing file. Open it and look; if it is a few bytes long, the deploy did not copy the real file, and the fix is in the build.
Repairing instead of reinstalling
If the plugin is custom and the original is gone, the header can be rewritten by hand. It needs a Plugin Name: line in a comment at the top of a top-level .php file, before any output. Once WordPress has deactivated a plugin for a bad header, its entry is already removed from the active plugins list, so activate it again from the Plugins screen after the fix; its settings in the database are untouched. Updating plugins one at a time, as in updating plugins safely, is what makes the moment a header broke easy to find.
Verify
The plugin appears in the list with its name and version and no error beneath it. Activate it; the activation succeeds without a fatal, which also confirms the main file is loading. If the error persists for a folder whose main file is present and has the header, check readability with the ls -l above — a file the web server cannot read is the one remaining explanation. If instead the message changed to "Plugin file does not exist", the file is missing, and the plugin needs reinstalling rather than repairing.
Frequently asked
- Something changed the main file: an edit that broke the comment block, a deploy that overwrote it with a stub, or a permissions change that left the web server unable to read it. If the file were missing altogether, WordPress would say 'Plugin file does not exist' instead.
- Same check, different moment. The installer scans the zip before copying it and prints that message when no file inside carries a Plugin Name line, usually because the zip is a marketplace bundle or has the plugin nested one folder too deep. The valid-header message comes from activation of an installed file.
- In any .php file at the plugin folder's top level, within its first 8 KB. WordPress scans each top-level file for a Plugin Name: line, in a block comment, a line comment or after a hash. Files in subfolders are not scanned.