Publishing a WordPress plugin to WordPress.org can feel surprisingly complicated the first time you encounter Subversion.
You may already use Git and GitHub every day, but WordPress.org uses SVN as its plugin release repository. That creates a different workflow—and a different collection of errors.
A release can fail because your files are in the wrong directory, your Stable Tag doesn’t match your plugin version, SVN doesn’t recognize your working copy, credentials aren’t accepted, or a release tag wasn’t created correctly.
The good news is that most WordPress SVN problems fall into a relatively small number of categories.
This guide covers the most common WordPress plugin SVN errors, what they mean, and how to fix them.
Why WordPress.org Uses SVN Differently From GitHub
Before troubleshooting SVN, it’s important to understand what WordPress.org expects from it.
WordPress describes its SVN repository as a release repository rather than a development repository. Developers are encouraged to do their day-to-day development elsewhere—such as GitHub—and push finished releases to WordPress.org SVN.
A typical WordPress plugin SVN repository looks like:
Each directory has a specific purpose.
trunk/ contains the current plugin code.
tags/ contains individual released versions.
assets/ contains WordPress.org directory assets such as banners, icons, and screenshots.
Understanding that structure prevents many of the errors below.
1. “Not a Working Copy”
One of the most common SVN errors looks similar to:
What it means
SVN doesn’t recognize the directory you’re working in as an SVN working copy.
Simply creating folders named:
doesn’t make the directory an SVN repository.
An SVN checkout contains hidden metadata that tells Subversion which WordPress.org repository the files belong to.
How to fix it
Check out the actual WordPress.org repository:
Then work inside the resulting directory.
You can verify it with:
If SVN returns repository information, you’re operating inside a valid working copy.
2. Authentication Failed
You may encounter an error such as:
or another authorization error when committing.
What it means
WordPress.org could not authenticate the credentials being used for the commit.
Your WordPress.org account must also have commit access to that particular plugin repository.
How to fix it
First verify that you’re using the correct WordPress.org username and credentials.
Then confirm that the account is actually a committer for the plugin.
It’s also worth remembering that SVN clients can cache credentials. If you’ve changed credentials recently, an older cached credential can sometimes continue being presented.
Before changing repository files, determine whether you’re dealing with a repository problem or an authentication problem.
3. Plugin Files Are Inside an Extra Folder
This mistake is easy to make.
You might accidentally produce:
That looks organized—but it is wrong for a WordPress.org plugin repository.
Correct structure
Your primary plugin files should instead be directly inside trunk:
WordPress specifically warns that putting the main plugin file inside another directory beneath trunk can break generation of the downloadable plugin ZIP.
4. Stable Tag Does Not Match the Plugin Version
This is one of the most important WordPress release problems.
Imagine your primary plugin file contains:
but readme.txt contains:
You now have conflicting release information.
How to fix it
For a normal release, keep these synchronized:
WordPress’s Plugin Review documentation specifically identifies an incorrect Stable Tag as a common issue and recommends keeping it aligned with the version in the main plugin file.
The Plugin Directory first reads Stable Tag from trunk/readme.txt, then uses that value to locate the corresponding release under /tags/.
5. “Stable Tag: trunk” Causes Problems
Historically, some developers used:
WordPress currently discourages this approach.
Better approach
Create an actual release tag:
and use:
WordPress says properly tagged releases are the fully supported approach and notes that using trunk as the stable tag can create problems with automatic updates.
6. The New Version Doesn’t Appear on WordPress.org
You committed the new plugin.
SVN says the commit succeeded.
But WordPress.org still appears to show the previous version.
Before immediately committing everything again, check four things:
Plugin header
readme.txt
SVN tag
SVN status/log
Confirm that the intended files actually reached the repository.
WordPress.org can also require processing time after SVN changes. The Plugin Handbook notes that SVN activity triggers rebuilding of plugin ZIP files and that updates can sometimes take time to propagate.
So don’t assume a delay means the commit failed.
7. The Plugin Page Changed, but the Readme Didn’t
This can be especially confusing.
You edit:
commit it, and expect the live WordPress.org plugin page to change.
Nothing happens.
Why?
Once Stable Tag points to a versioned release, WordPress.org uses the files associated with that stable release.
For example:
points WordPress.org toward:
The WordPress documentation explains that once the stable tag resolves to an existing release, subsequent plugin-page parsing comes from that referenced version rather than continuing to use the rest of the trunk readme.
This is why keeping your release metadata synchronized matters so much.
8. Banner or Plugin Icon Doesn’t Appear
Your code works.
Your release is live.
But the WordPress.org banner or icon is missing.
The problem may simply be where you put the image.
Wrong
Correct
WordPress.org’s directory graphics belong in the top-level SVN assets/ directory—not inside the plugin’s trunk or release tag.
Also remember that WordPress.org serves these images through a CDN and caches them heavily. An asset change may therefore not appear immediately.
9. SVN Doesn’t Include a New File
You copied a new file into your plugin and committed, but it never appeared on WordPress.org.
The reason may be simple:
SVN wasn’t told to track it.
Check:
A new untracked file will generally appear with:
Add it:
Then check again:
Before every release, reviewing svn status is one of the simplest ways to catch missing, added, modified, or deleted files before committing.
10. Deleted Files Keep Appearing
The reverse problem can happen too.
Deleting a file in Finder or another file manager doesn’t necessarily mean you’ve correctly recorded the deletion in the SVN release workflow.
Use:
and make sure the deletion is represented correctly.
When intentionally removing a tracked file, using SVN’s own delete operation makes your intent explicit:
Then commit the change.
11. “File Already Exists” or Tag Already Exists
Suppose you’re releasing:
but:
already exists.
Do not casually overwrite an existing released tag.
Version tags should represent immutable releases.
If you’re shipping another release, increment the plugin version:
Then create:
WordPress’s current release-confirmation documentation goes even further for releases using that system: once the release is confirmed, alterations cannot be made to the tagged version.
Treating tags as immutable is therefore an excellent release discipline regardless.
12. You Copied the Release Into tags Instead of Using SVN
A normal filesystem copy may appear to work:
But WordPress recommends creating the release tag through SVN itself:
Then commit:
Using svn cp preserves SVN history and makes the relationship between trunk and the tagged release clear.
13. Your Plugin ZIP Contains Another Plugin Folder
This often happens before SVN even enters the picture.
You intend to release:
but your ZIP actually contains:
That extra nesting can create problems when preparing the release.
Before publishing, inspect the ZIP structure and make sure the top-level plugin directory contains the actual plugin bootstrap file.
This is particularly important when your development project contains build folders, release folders, source packages, or other artifacts that don’t belong in the WordPress.org release.
14. WordPress.org Is Showing the Wrong Version
This usually comes back to three pieces of metadata disagreeing.
Check:
WordPress.org explains that the version displayed for the plugin comes from the main plugin PHP file, while the Stable Tag determines which tagged release the directory should use.
A mismatch can therefore produce surprisingly confusing results.
15. SVN Commit Succeeded, but the Release Still Isn’t Live
There’s another possibility now: Release Confirmation.
WordPress.org offers an opt-in Release Confirmation feature. When enabled, creating a new SVN release tag triggers a pending release that a plugin committer must confirm through the Release Management dashboard.
So if everything in SVN looks correct but a release isn’t proceeding, check whether Release Confirmation is enabled for that plugin and whether a confirmation email is waiting.
16. You’re Treating WordPress SVN Like GitHub
This isn’t technically an SVN error, but it causes many workflow problems.
A developer accustomed to Git might make commits for:
That’s normal in a development repository.
It’s not how WordPress.org wants its plugin SVN repository used.
WordPress explicitly asks developers to avoid frequent commits because each SVN commit can trigger regeneration of plugin ZIP files. The repository is intended primarily for releases.
A better architecture is:
Use Git for development history.
Use WordPress SVN for publishing finished releases.
A WordPress SVN Release Checklist
Before committing a release, verify:
- The primary plugin PHP file is directly inside
trunk/. - The plugin version has been incremented.
Stable Tagmatches the intended release.- A corresponding versioned directory exists under
tags/. - New files have been added to SVN.
- Deleted files are correctly recorded.
- WordPress.org banners, icons, and screenshots are in top-level
assets/. readme.txtis valid and current.svn statusshows exactly the changes you expect.- You’re committing from the correct WordPress.org repository.
- Your WordPress.org credentials have commit access.
- You’re publishing finished release code—not using SVN for routine development.
These practices closely follow the workflow WordPress documents for its Plugin Directory.
WordPress SVN Doesn’t Have to Be the Hard Part of Releasing a Plugin
SVN itself is reliable.
The difficulty is that publishing a WordPress plugin involves coordinating several things at once:
A mistake anywhere in that chain can delay a release or result in WordPress.org receiving something other than what you intended.
That’s one of the reasons we built WordPress Plugin Publisher.
Instead of manually managing each part of the WordPress.org release process, Publisher provides a visual workflow for preparing, reviewing, and publishing plugin releases while still using the official WordPress.org SVN infrastructure.
WordPress Plugin Publisher doesn’t replace WordPress.org SVN. It makes the WordPress.org publishing workflow easier to manage.
Start with a 7-day free trial, or purchase a license for $69/year.