For the most part, I think WordPress is a pretty solid platform. Of course, we complicate things when we drag third-party elements into it for the sake of improving performance or security, adding new design features, or opening up greater functionality. But the payoff is generally worth it. Without those integrations, you’d have to do much more manual coding and that just doesn’t isn’t the most effective way to build a website these days.
That said, there are times when issues arise when you try using WordPress plugins and themes on your website. As I’ve talked about before, there are WordPress plugin conflicts that occur upon initial installation or during updates. But there are other ways in which they can cause issues for you before you even get them on the site.
Below, I’m going to break down the 7 reasons why a WordPress plugin or theme won’t install on a website and some ways to get around these errors.
7 Reasons Why Your WordPress Plugin or Theme Won’t Install
The nice thing about these kinds of WordPress errors is that they’re easy to identify. Usually, there’s an error message that accompanies each failure to load, so there isn’t as much troubleshooting with something like this as there are with other WordPress errors. It’s just more annoying than anything else.
So, here are the most common reasons why your WordPress plugin or theme won’t install and what to do about them:
1. Uploading the Wrong File Format
Typically, you’ll encounter an installation error during the manual upload of a theme or plugin through the Add New / Upload option in WordPress (as opposed to directly installing from the WordPress repository):
When you see the following “bad format” message, it means that you have not uploaded the native files provided to you by the theme or plugin developer.
The only plugin or theme files that should ever be uploaded to WordPress are zip files.
Before you get in touch with the plugin or theme developer, verify that you didn’t receive the correct file from them. If this came from your client, they may have unzipped the folder and given you what they thought was the correct file from within. If it didn’t come from the client and you really don’t have the right folders, get in touch with the developer.
2. Missing Files
Now, let’s say you did try and upload a zip file into WordPress, but you saw this error message instead:
This means that the files contained within the folder are not what WordPress was expecting.
Unzip the folder and review the contents. Is this even the correct zip? Does it contain all the files you would expect a plugin or theme to have? You can cross-check the contents of the folder against WordPress’s recommendations for files that should be included in the package:
If you’ve detected any missing files, reach out to the developer for assistance.
3. Syntax Error
When you purchase a WordPress plugin or theme from a reputable developer, you shouldn’t have to worry about this kind of error occurring.
However, let’s say your client was trying to cut corners and save money, and so they found some plugin or theme online that looked promising. You try to install it in WordPress and you receive a syntax error. It’ll usually say something about “parse error” and “syntax error”.
All this means is that there’s something wrong in the code. This error can actually come up if you erroneously try to edit a theme or plugin once it’s installed on your website. However, if you’re seeing it during installation, then the error lies with the developer.
If you want to review the code of the plugin or theme on your own, you might be able to detect and repair the error yourself. Before you dig in, check into any other reported issues with the plugin or theme if there’s a support system attached to it (through WordPress or a marketplace).
If there aren’t any, your safest bet might be to have your client get a new plugin or theme. If you don’t trust the developer to code the backend well, this issue could keep coming up with each new update (and you don’t want to deal with that).
4. Uploading the Wrong Zip File
This error is one you’re probably going to encounter with larger, multipurpose themes. You received a zip file from your client and, by all intents and purposes, it looks to be in good shape. However, let’s say you go to add the new theme:
Then you see this error:
In actuality, the stylesheet is not missing. You probably just downloaded the wrong version of the theme file.
Some developers offer up different zip packages for their themes, especially if they’re including plugins and child themes within them. Here’s an example of how Uncode includes various download options on Themeforest:
While it’s essential to have that full file with all the documentation, licenses, plugins, and alternate themes, that file cannot be uploaded into WordPress because it looks like this:
WordPress can unzip the top-level zip file, but it won’t be able to go through and unzip everything else contained within the folder. If you want to get your theme in there, then you need to upload the proper zip file.
5. Exceeding the Memory Limit
I touched on this error recently when I talked about the server issues that affect WordPress. Basically, this happens when your web hosting PHP memory limit is too low to process the installation.
The error will say something like, “Fatal error: Allowed memory size of _______ bytes exhausted…” If you see this memory error, it’s easy to fix.
Log into the control panel of your site and open your preferred file editor: FTP or file manager. In the root directory, you’ll find your wp-config.php file. Click on the edit button and add the following line of code:
define( 'WP_MEMORY_LIMIT', '256M' );
Since the default memory limit is usually 64M, this will significantly increase it and help you get your new theme or plugin installed without issue.
6. Exceeding the File Size Limit
Memory isn’t the only thing that can be pushed to its limit when uploading a new WordPress plugin or theme. You may also find that the allowable file size is exceeded. When this occurs, you’ll see a message similar to this:
“The uploaded file exceeds the upload_max_filesize directive in php.ini”
To fix this maximum upload limit, you’ll need to do so through the control panel. Access your directory using either FTP or a file manager. Once you’re in there, locate the wp-admin folder.
Do you see a php.ini file? If not, you’re going to have to create one.
Once you have the php.ini file open, look for a section that mentions “filesize”. If it exists, you’ll want to overwrite it with the following code. If it doesn’t, then enter the following lines of code into the file:
upload_max_filesize = 1000M
post_max_size = 2000M
memory_limit = 3000M
file_uploads = On
max_execution_time = 180
This will give you some more leeway in how large your WordPress theme and plugin files can be. If you’re still experiencing problems with this error, read through Jenni McKinnon’s guide on how to increase the maximum upload limit.
7. Miscellaneous Errors
I’m including this final hodgepodge error type because you never know what types of external conflicts might get in the way of you being able to install a plugin or theme. In my case, it was an old conflict between an SSL certificate and CDN I had on my site.
In a nutshell, here’s what happened:
- I bought a new WordPress theme.
- I installed the WordPress theme and activated it.
- When I uploaded the theme, I received a bunch of error messages about how some of the plugins wouldn’t install. I initially disregarded the message because I didn’t think I was going to use most of the plugins anyway.
- As it turns out, before I could customize or use my theme, I had to activate a required plugin from the developer… which would not install. The message below is what I saw.
I’ve had an SSL certificate on my website for over a year and had experienced issues with it in the past. Specifically, it conflicted with the CDN. To resolve the conflict, I asked my web host to get rid of the CDN. As far as I knew, the issue was fixed. (Funny enough, the CDN ended up being the problem here.)
Anyway, after working in conjunction with my web hosting company and the theme developer, we were able to sort out that the error could be bypassed by uploading the plugin files directly into WordPress. I had assumed that an inability to install through the theme upload would mean an inability to install through the normal process. However, the workaround took and I was able to get the plugin installed on my site.
I guess this is my roundabout way of saying that if you encounter an error during the installation of a WordPress plugin or theme, it doesn’t resemble numbers 1 through 6 above, and you’ve tried manually uploading, go to the perceived source of the problem. They should be able to provide you with insights into the problem and spare you the agony of trying to figure it out on your own.
Wrapping Up
So, is there a way to avoid these in the future? Well, using reputable themes and plugins from WordPress developers is a good place to start. Familiarizing yourself with what theme and plugin files should contain is another good thing to have under your belt.
All in all, I think this is probably one of the easier kinds of errors you might end up having to deal with in WordPress. That said, errors are a nuisance you often can’t afford to deal with when they pop up mid-workflow, so make sure you’re well-versed in what the most common errors are and how to go about fixing them.
Tags:
