Short summary:
This error means WordPress can’t find a valid plugin header comment in the plugin’s main PHP file. Causes: corrupted/partial download, bad ZIP extraction, wrong file moved into plugin folder, BOM/extra whitespace, wrong filename, permissions preventing reading, or a malformed header. Below is a full, copy-pasteable, step-by-step troubleshooting & repair guide (what, why, how), plus what not to do, and SEO metadata.

What is the “plugin header” (quick)

A plugin header is a PHP comment block at the top of the plugin’s main file that tells WordPress the plugin name, author, version, etc. Example minimal header:

<?php
/*
Plugin Name: My Example Plugin
Plugin URI: https://example.com/my-plugin
Description: Short description of plugin.
Version: 1.2.3
Author: Jane Doe
Author URI: https://example.com
Text Domain: my-example-plugin
*/

If WordPress cannot find Plugin Name: in a top-level PHP file (first ~ 8 KB), it shows “does not have a valid header.”

---

Full step-by-step troubleshooting & fixes

Before you start: Always backup your site (files + DB). Don’t edit live files without a backup.

---

1) Confirm the exact error and plugin folder

What to do:

• Try activating the plugin from WP admin to reproduce the error and note the plugin folder name.
• Look in wp-content/plugins/ for the plugin directory name.

Why:

• Sometimes the ZIP contains an extra parent folder (e.g. plugin-1.0/plugin/), so WordPress can’t find the main plugin file where it expects.

How:

# list plugin folder
ls -l /path/to/wordpress/wp-content/plugins/

Fix if wrong folder structure:

• If you see nested folders like my-plugin-1.0/my-plugin/my-plugin.php, move the correct folder so the main plugin file is inside wp-content/plugins/my-plugin/ (not extra nesting).

---

2) Check for partial or corrupted download

What to do:

• Delete the plugin folder, re-download the plugin ZIP from the official plugin repo, and re-upload/extract carefully.

Why:

• A corrupted or partial ZIP extract may create broken PHP files or missing headers.

How (SSH example):

cd /path/to/wordpress/wp-content/plugins
rm -rf my-plugin                 # remove broken install (backup first if needed)
wget https://downloads.wordpress.org/plugin/my-plugin.latest-stable.zip -O /tmp/my-plugin.zip
unzip /tmp/my-plugin.zip -d /tmp/
# inspect extracted contents to find the real plugin dir, then move
mv /tmp/my-plugin /path/to/wordpress/wp-content/plugins/my-plugin
chown -R www-data:www-data /path/to/wordpress/wp-content/plugins/my-plugin
chmod -R 755 /path/to/wordpress/wp-content/plugins/my-plugin

If you don’t have SSH:

• Use the hosting control panel’s File Manager: delete plugin folder → upload fresh ZIP → extract → ensure extracted folder is directly inside wp-content/plugins/.

Note: Some hosts or FTP clients corrupt ZIP transfer if using ASCII mode — always use binary mode when transferring ZIPs.

---

3) Inspect the plugin’s main file header (open the plugin’s main PHP file)

What to do:

• Find the file that should contain the header (common names: plugin-name.php, index.php, or a file specified in readme). Open the top of the file and confirm the header is present and syntactically correct.

Why:

• If the header is missing or comments were stripped by a bad extraction, WordPress will not recognize the plugin.

How (view first 50 lines):

head -n 50 /path/to/wordpress/wp-content/plugins/my-plugin/my-plugin.php

Look for a properly formed block with Plugin Name:. If it’s missing, the plugin is corrupted or you’re opening the wrong file.

---

4) Remove BOM / extra whitespace and ensure PHP opening tag is first

What to do:

• Ensure the PHP file begins with <?php and no whitespace, no new-lines, no BOM before it.

Why:

• A BOM (Byte Order Mark) or invisible characters before <?php can break PHP parsing or cause WordPress not to detect the header properly.

How:

• Open the file in a code editor (VSCode, Sublime) and set encoding to UTF-8 without BOM. Or use sed/awk to check/remove BOM.

Check BOM presence:

# show bytes of first 4 characters
xxd -l 4 -g 1 /path/to/plugins/my-plugin/my-plugin.php

Remove BOM (example using awk):

awk 'NR==1{sub(/^\xef\xbb\xbf/,"")}{print}' /path/to/plugins/my-plugin/my-plugin.php > /tmp/tmp.php && mv /tmp/tmp.php /path/to/plugins/my-plugin/my-plugin.php

Also ensure there’s no blank line before <?php.

---

5) Verify file encoding & line endings

What to do:

• Ensure files are UTF-8 without BOM and use Unix line endings (LF).

Why:

• Some Windows editors or packaging compressions change encoding/line endings; WordPress can still read them but BOM is the main culprit.

How:

• Convert with dos2unix and confirm with file:

file /path/to/plugins/my-plugin/my-plugin.php
dos2unix /path/to/plugins/my-plugin/*.php

---

6) Check plugin files haven’t been renamed / index.php conflicts

What to do:

• Sometimes the main file is renamed to something unexpected, or an index.php with no header exists at top-level and WP reads that first. Make sure the main plugin file contains the header (not a blank index.php).

Why:

• WP scans all top level files for headers; if header is missing in all, plugin invalid.

How:

• List files and open likely candidates:

ls -1 /path/to/plugins/my-plugin

---

7) Permissions & ownership checks (so WP/PHP can read the file)

What to do:

• Ensure files are readable by the webserver/PHP user.

Why:

• If files are not readable, WP might fail to parse them.

How:

# common web users: www-data (Debian/Ubuntu), apache (CentOS)
chown -R www-data:www-data /path/to/wordpress/wp-content/plugins/my-plugin
find /path/to/wordpress/wp-content/plugins/my-plugin -type d -exec chmod 755 {} \;
find /path/to/wordpress/wp-content/plugins/my-plugin -type f -exec chmod 644 {} \;

Do NOT use 777.

---

8) Use WP-CLI to inspect/verify plugin

What to do:

• If you have WP-CLI, use it to list plugins and inspect activation errors.

Why:

• WP-CLI often gives clearer diagnostic messages and can install/activate reliably.

How:

# list plugin files
wp plugin list --path=/path/to/wordpress

# try activating (shows errors)
wp plugin activate my-plugin --path=/path/to/wordpress

If WP-CLI shows same header error, the plugin main file is malformed or missing header.

---

9) Confirm ZIP packaging from repo (compare checksums if possible)

What to do:

• Re-download from wordpress.org and compare size/checksum with your copy.

Why:

• Rarely, a mirrored repo or network error may deliver corrupted ZIP.

How:

# example
wget -O /tmp/my-plugin.zip https://downloads.wordpress.org/plugin/my-plugin.latest-stable.zip
sha256sum /tmp/my-plugin.zip
# compare with your downloaded version (if you saved it)
sha256sum /tmp/your-copy.zip

If mismatch, re-download and re-install.

---

10) Reinstall using WordPress admin (reupload plugin zip)

What to do:

• Delete the broken plugin (via WP admin or FTP), then in WP admin Plugins → Add New → Upload Plugin → choose fresh ZIP from official repo → Install Now → Activate.

Why:

• Admin uploader handles extraction more reliably on many shared hosts.

CAUTION: Delete only if you have backup of plugin settings or you know the plugin stores config in DB. Some plugins lose settings on delete — check plugin docs.

---

11) Special case — plugin is a multi-file package (composer / vendor)

What to do:

• If the plugin uses composer or bundles vendor files, ensure extraction kept directory structure intact (e.g., my-plugin/vendor/autoload.php exists).

Why:

• If plugin’s main file expects vendor autoload and it’s missing, plugin will fail (but usually with PHP errors; header may also be in different file).

How:

• Confirm vendor and required files exist. If missing, get official packaged ZIP that contains vendors or run composer where appropriate.

---

12) If plugin is from a repo but replaced with a zip containing only one folder (e.g., docs)

What to do:

• Inspect the ZIP — sometimes plugin authors include an extra root folder (like my-plugin-1.0.0) — you must move files into plugin folder.

Why:

• WordPress expects plugin files directly under wp-content/plugins/plugin-folder/.

---

13) Final fallback — manual create plugin header (only if safe)

What to do:

• If the plugin is a custom script missing header (rare for repo plugins), you can add a header block to the main file to let WP recognize it. Use only if you know which file is intended as main plugin file.

Example add at top (edit carefully):

<?php
/*
Plugin Name: My Plugin Temp Fix
Description: Temporary header added to test if plugin loads. Remove after verifying.
Version: 1.0
Author: You
*/

Why:

• This helps detect whether the plugin is functionally intact but missing header. If code still errors after activation, revert and use official package.

Warning: Do not add header to the wrong file or modify third-party plugin code dangerously — better to re-download official package.

---

Quick checklist (one-line actions)

1. Backup files & DB.
2. Delete broken plugin folder.
3. Re-download official ZIP.
4. Upload/extract ensuring correct folder level.
5. Confirm main plugin PHP has Plugin Name: header.
6. Remove BOM / whitespace before <?php.
7. Ensure permissions readable by webserver.
8. Activate via WP admin or WP-CLI.

---

Common root causes (why this happens)

• Corrupted ZIP download (network errors, proxy, caching).
• Bad extraction (control panel or FTP extraction flattened files or added extra nesting).
• Extra parent folder inside ZIP (common when vendors upload repo bundles).
• BOM / encoding issues from Windows editors.
• Wrong file permissions / ownership making file unreadable.
• Plugin package missing vendor files (composer-based plugin packaged incorrectly).
• You uploaded only a subfolder (docs) or wrong archive.

---

What NOT to do

• Do NOT set plugin PHP files to 777. (Security risk.)
• Do NOT edit plugin code randomly without backups.
• Do NOT copy plugin files into wp-content/plugins with extra nesting — place the true plugin folder directly inside plugins/.
• Do NOT activate a plugin if PHP errors occur — check log first.
• Do NOT modify core WordPress files to “fix” plugin issues.

---

Additional useful commands & checks

View PHP error logs (may contain parse errors):

tail -n 200 /var/log/php8.1-fpm.log   # adjust path & php version
tail -n 200 /var/log/apache2/error.log
tail -n 200 /var/log/nginx/error.log

Find files with BOM (quick heuristic):

grep -rlI $'\xEF\xBB\xBF' /path/to/wordpress/wp-content/plugins/my-plugin || echo "No BOM found"

WP-CLI reinstall (force):

# remove and install
wp plugin delete my-plugin
wp plugin install my-plugin --activate
# or install from file
wp plugin install /tmp/my-plugin.zip --activate

---

Example quick flow for non-technical users (cPanel / Shared hosts)

1. Backup via control panel.
2. Go to File Manager → wp-content/plugins/ → delete the problematic plugin folder.
3. Plugins → Add New → Upload Plugin → choose fresh zip from wordpress.org → Install Now → Activate.
4. If upload fails, contact host support with exact error and ask them to check file permissions and ZIP extraction.