4 WordPress Plugin Submission Traps That Blocked Our WP.org Approval
We built FormIQ — an AI-assisted intake form plugin for allied health practices in Australia. The plugin logic worked perfectly. The submission to WordPress.org did not.
Between the first submission and final approval, we hit four separate automated gatekeepers — each returning a different error, each requiring a fix, each extending the timeline. None of them were about the plugin’s functionality. All of them were about packaging and metadata.
If you are building a WordPress plugin and planning to submit to the directory, read this first. Every one of these blockers is entirely preventable with ten minutes of preparation.
Background: What the WP.org Submission Process Looks Like
When you submit a plugin to WordPress.org, your zip file goes through an automated scan first, then a human review queue. The automated scan is what caught all four of our issues.
Your plugin zip
│
▼
┌─────────────────────────────────────┐
│ WP.org Automated Scanner │
│ Checks: headers, versions, │
│ readme, textdomain, │
│ security patterns │
└─────────────────────────────────────┘
│
├──► PASS ──► Human review queue (days to weeks)
│
└──► FAIL ──► Email with error list
Fix → Resubmit → RescanEach scan–fail–fix cycle adds time. The human review queue is meaningful — reviewers are volunteers and the queue moves slowly. You want to get through the automated scan cleanly on the first pass.
Here are the four things that blocked us.
Trap 1: readme.txt Title Doesn’t Match Plugin Header Name
What the scanner reported:
WARNING: mismatched_plugin_name
Plugin name "FormIQ — AI Intake Forms for Allied Health"
is different from the name declared in plugin header
"FormIQ — AI Intake Forms".What happened:
The plugin’s PHP file had:
Plugin Name: FormIQ — AI Intake FormsThe readme.txt had:
=== FormIQ — AI Intake Forms for Allied Health ===We had updated the readme.txt title to include “for Allied Health” as we refined the positioning. We never updated the PHP header to match. The scanner caught the discrepancy.
The fix:
These two must be character-for-character identical:
Sync check before submission:
Plugin file header: "FormIQ — AI Intake Forms for Allied Health"
readme.txt title: "FormIQ — AI Intake Forms for Allied Health"
└── Must match exactly, including punctuationPick your final plugin name before submission. Update both places simultaneously. Do not let them drift.
Severity: Warning (not a hard block, but adds review friction and can delay approval)
Trap 2: “Tested up to” Version Was Stale
What the scanner reported:
ERROR: outdated_tested_upto_header
Tested up to: 6.7 < 6.9. Plugin will not show in searches.This one was a hard error — the plugin would not appear in WordPress.org search results until resolved.
What happened:
We had been developing the plugin against WordPress 6.7. By the time we submitted, WordPress 6.9 had been released. Our readme.txt still declared:
Tested up to: 6.7The scanner knew the current WordPress version and flagged any plugin declaring a Tested up to value more than one major version behind.
The fix:
Before every submission or update:
Step 1: Check current WordPress version
wordpress.org/download → note the version number
(as of April 2026: WordPress 6.9)
Step 2: Test your plugin against that version
Spin up a local WordPress 6.9 instance
Run your core plugin workflows
Confirm nothing is broken
Step 3: Update readme.txt
Tested up to: 6.9
Step 4: Repackage and submitThis takes 30–60 minutes for a typical plugin and should be done as close to submission day as possible. WordPress releases frequently — a tested version can become “stale” by the scanner’s definition within weeks.
Severity: Error (hard block — plugin won’t appear in search without fixing this)
Trap 3: textdomain_mismatch Warning (That You Should Ignore)
What the scanner reported:
WARNING: textdomain_mismatch
The "Text Domain" header in the plugin file does not match
the slug. Found "formiq", expected "formiq-ai-intake-forms".What happened:
When you first submit a plugin, WP.org assigns a slug based on the plugin name — typically a lowercase, hyphenated version. Our plugin got the slug formiq-ai-intake-forms. Our PHP file had:
Text Domain: formiqThe scanner expected:
Text Domain: formiq-ai-intake-formsHere is the critical thing we learned: do not fix this pre-approval.
The WP.org review documentation and community forums are clear on this: the text domain in your plugin should match what you actually use in your code’s translation functions. If your entire codebase calls __('Some text', 'formiq'), changing the text domain header to formiq-ai-intake-forms without updating every single translation call will break your internationalisation entirely.
More importantly: once your plugin is approved and assigned a slug, WP.org updates the expected text domain. The warning disappears post-approval without any code change.
The fix:
Pre-approval:
─────────────────────────────────────────────────
Ignore this warning. Do not change text domain.
It is a pre-approval false positive.
Every new plugin submission gets this warning.
Post-approval:
─────────────────────────────────────────────────
If you want alignment with your slug:
1. Update Text Domain header in PHP file
2. Do a global find-replace on the text domain
in all __(), _e(), esc_html__() calls
3. Test translations are still working
4. Submit as an update, not a new submissionWe spent two hours researching this before concluding the correct action was to do nothing. Save yourself the time.
Severity: Warning (cosmetic — does not block approval, resolves automatically post-approval)
Trap 4: readme.txt and LICENSE Were Missing From the Zip
This one was the most avoidable — and the most impactful. The plugin was approved, we published it, and the WP.org listing page showed no description, no changelog, no FAQ. Just the plugin name on a blank page.
What happened:
We had a custom packaging script (package.mjs) that built the plugin zip. It was written incrementally — we added the PHP file, the includes/ directory, the build/ output, and the assets/ folder. readme.txt and LICENSE were sitting at the project root and were simply never added to the packaging script.
The files existed. They were just not in the zip.
Our packaging script logic (simplified):
function buildPluginZip():
create empty zip archive
add "formiq.php" ✓ included
add "includes/" folder ✓ included
add "build/" folder ✓ included
add "assets/" folder ✓ included
// readme.txt ✗ FORGOTTEN
// LICENSE ✗ FORGOTTEN
save zip as "formiq.zip"The WP.org automated scanner passed the zip because a plugin can technically function without readme.txt. But the listing page renders from readme.txt — no file means no listing content.
The fix:
Add a verification step to every packaging workflow:
Before uploading to WP.org, verify zip contains:
─────────────────────────────────────────────────
□ readme.txt (required for listing)
□ LICENSE (required for review)
□ {plugin-name}.php (main plugin file)
□ includes/ (if applicable)
□ assets/ (screenshots and banners)
Verification command (pseudocode):
list contents of zip file
for each required file in checklist:
if file not in zip → raise error before uploadFive minutes of verification prevents discovering the problem after your plugin is live and showing a blank listing to thousands of potential users.
Severity: P2 — plugin listing is broken after approval, requires immediate fix update
The Full Pre-Submission Checklist
Combining all four lessons into one checklist you can run before every WP.org submission:
┌──────────────────────────────────────────────────────────┐
│ WP.org PLUGIN SUBMISSION CHECKLIST │
├──────────────────────────────────────────────────────────┤
│ METADATA ALIGNMENT │
│ □ Plugin Name in PHP header matches readme.txt title │
│ (character-for-character, including punctuation) │
│ │
│ VERSION FRESHNESS │
│ □ "Tested up to" = current WordPress version │
│ □ Tested locally against that version │
│ □ "Requires at least" is correct │
│ │
│ TEXTDOMAIN │
│ □ textdomain_mismatch warning → ignore pre-approval │
│ □ Do NOT change text domain before approval │
│ │
│ ZIP CONTENTS │
│ □ readme.txt is in the zip │
│ □ LICENSE is in the zip │
│ □ Main PHP file is in the zip │
│ □ No .git, .DS_Store, node_modules in zip │
│ □ Zip extracts to a single folder named after slug │
└──────────────────────────────────────────────────────────┘How Long Did All This Add to Our Timeline?
Here is the actual timeline from first submission to approval:
Day 1: First submission
Day 2: Automated scan returns errors #1 + #2
Day 3: Fix name mismatch + tested-up-to, resubmit
Day 4: Automated scan passes, enters human review queue
Day 17: Human reviewer responds with questions
Day 19: Questions answered
Day 23: Approved
Day 23: Listing live but blank (missing readme.txt in zip)
Day 24: Fix applied (zip updated with readme.txt)
Day 25: Listing shows full contentTotal: 25 days from first submission to a fully functional listing. Without the automated scan failures, we would have entered the human review queue on Day 2 — potentially saving 15 days of delay.
If You Are Submitting a Plugin Soon
The WP.org directory is competitive. A plugin that clears the automated scanner quickly, has a complete listing from day one, and does not require back-and-forth with reviewers will always outperform an equivalent plugin that drags through the process.
If you are building a WordPress plugin for your Australian business and would like a pre-submission review, Cosmos Web Tech’s WordPress development team can run through this checklist with you before you submit. We have been through this process for several plugins and know where the automated scanner will look.
For more on WordPress plugin architecture for Australian healthcare practices, see our related guide: Building GDPR and Privacy Act Compliant Contact Forms in WordPress.
Your website’s performance depends on what’s behind it. Cloud Geeks provides the managed hosting, cloud, and IT support that keeps Australian SMBs online and secure.
Ash Ganda covers how Australian SMBs are using AI, automation, and digital strategy to grow without scaling costs proportionally.
If your business is also planning a customer-facing iOS or Android app — Awesome Apps builds cross-platform mobile apps for Australian SMBs.
Part of the Ganda Tech Services family, Cosmos Web Tech delivers specialist web design and digital marketing for Australian small and medium businesses.