You select an image, click Upload, and WordPress displays an error. Sometimes it names the problem, such as a file exceeding the upload limit. Sometimes it only says “HTTP error” or reports that the image cannot be processed.
The first useful question is whether the failure affects one file, larger images, or every upload.
This guide explains what to check first when you encounter a WordPress media upload error. Start with a small test file and the exact error message, then investigate the relevant limits or server settings.
Start With These Three Checks
- Record the exact message and the time of the failure.
- Try one small, known-good JPEG through Media → Add New.
- Compare that result with the original file and upload method.
For the test, use an ordinary image that opens correctly on your computer and sits comfortably below the displayed upload limit. A file of a few hundred kilobytes is a practical example.
If the small JPEG works, you have a useful comparison. It does not establish the precise cause of the original failure.
Match the Error to the Next Check
| Message or symptom | What to investigate |
|---|---|
| File exceeds the maximum upload size | File size and effective request limits |
| File type is not allowed | Actual format, allowed types, and account or network restrictions |
| Unable to create a directory | Upload path, ownership, permissions, and storage |
| Missing a temporary folder | PHP temporary-upload configuration |
| Failed to write file to disk | Storage and write access |
| Image cannot be processed | Dimensions, file integrity, and image-processing support |
| HTTP error | The failed request’s response and server logs |
| File appears in the library but upload reports failure | Incomplete processing or an invalid response |
PHP documents distinct errors for oversized uploads, temporary-folder problems, partial uploads, and disk-write failures. Treat the message as evidence for the next check. Manual
1. Check the Original File
Open It Before Uploading
Confirm the image or document opens correctly in a suitable application.
For an image, export a fresh copy as JPEG or PNG and retry. Keep the original separately.
Changing a filename extension does not convert the file. A file renamed from .heic to .jpg still needs a real conversion.
WordPress checks file extensions and detected types during upload, and can reject files that fail those checks. Developer.WordPress.org
Simplify the Filename
Use a clear name such as office-cleaning-team.jpg for the test. This helps eliminate unusual filename handling by plugins or hosting rules.
Treat renaming as a comparison test. It will not resolve a size limit or a damaged file.
Compare File Size and Pixel Dimensions
Compressed file size and image dimensions are different properties.
A photograph can have a manageable download size while requiring substantial resources to decode or resize. Try a reduced-dimension copy appropriate to its intended use.
For example, a very large camera image may not need its original dimensions for a blog illustration. Choose the export size based on the design, rather than a universal upload rule.
2. Check WordPress’s Upload Information
Open Media → Add New and note the displayed maximum upload size.
Then go to Tools → Site Health → Info and inspect the relevant server, media-handling, and filesystem information. WordPress documents fields for upload availability, effective size limits, and image-processing libraries such as Imagick and GD. WordPress.org
A missing optional library is a clue, not proof that every upload should fail. Format support depends on the available processing tools and the upload workflow.
If the message specifically says the server cannot generate image sizes for that format, try a properly exported JPEG or PNG. WordPress’s media API includes this type of diagnostic response. Developer.WordPress.org
3. Understand Which Size Limit Applies
PHP uses separate settings for individual files and complete requests.
| Setting | What it limits |
|---|---|
upload_max_filesize | A single uploaded file |
post_max_size | The complete POST request |
| Server, proxy, or CDN body limit | The request accepted before or around PHP |
| Hosting or network quota | Storage or account-level allowance |
WordPress explains that PHP upload and POST limits must be configured consistently. The complete request includes more than the file itself, so leave appropriate room for its additional data. Developer.WordPress.org
Increasing one setting may leave a lower limit elsewhere.
If an increase is justified, ask your host which setting controls the rejected request. Use the supported hosting configuration method and back up any file before editing it.
4. Check Storage, Temporary Files, and Write Access
If small files fail too, inspect hosting storage and upload-directory access.
Ask your host to check:
- Available disk space and account quota.
- File-count or inode limits.
- The PHP temporary-upload directory.
- The active WordPress upload path.
- Ownership and permissions for the destination directory.
The usual upload location is under wp-content/uploads, but offloading and custom configurations can change where files are handled.
WordPress’s documentation notes that appropriate permissions are necessary for media uploads. Have your host correct ownership and access for the actual setup rather than applying broad permissions across the site. WordPress.org
5. Identify the Failed Request Behind an HTTP Error
Open your browser’s Developer Tools, select Network, and retry once. Find the upload request and inspect its status and response.
| Response | What it indicates |
|---|---|
| 413 | The request exceeds a server-defined size limit |
| 403 | The request was understood but refused |
| 500 | An unexpected server-side failure |
| Timeout or gateway error | The request did not complete through the relevant server path |
These responses narrow the investigation. A 403 does not establish that a security plugin is responsible, and a 500 does not establish a memory shortage. MDN
A response may contain a more specific WordPress error even when the browser’s status appears successful. Read both the status and body.
Give hosting support the timestamp and request details so they can find the matching log entry.
6. Compare the Browser and Upload Method
Try a fresh login, another supported browser, or a private window with unnecessary extensions disabled.
Also compare uploading through the Media Library with uploading inside the post editor or page builder.
| Test result | Useful next direction |
|---|---|
| Media Library works, page builder fails | Investigate the editor or builder workflow |
| One browser fails | Check its session, extensions, and browser-side processing |
| One format fails | Check the file and format support |
| Large images fail, small images work | Investigate size, dimensions, processing, and time limits |
| All upload methods fail | Check shared hosting, permissions, and site-level settings |
The upload path can matter because current WordPress workflows may involve browser-side media processing as well as server-side handling. Developer.WordPress.org
7. Investigate Plugins and Security Rules
Review recent changes to image optimization, media offloading, security, and editor plugins.
On a staging copy where possible, test one suspected plugin at a time. Use the same file for each comparison and restore the intended configuration afterward.
For a blocked request, ask the host or security provider to identify the rule and review whether it is a false positive.
Avoid disabling upload validation or enabling every file type as a general repair. Those changes do not explain the original failure.
Worked Example
Suppose a blogger’s large PNG fails, but a small JPEG uploads successfully.
A practical sequence is:
- Record the PNG’s size and dimensions.
- Confirm it opens correctly.
- Export a smaller-dimension copy.
- Test through the Media Library.
- Inspect the failed response if the original still fails.
- Ask the host to check logs and image-processing limits.
If the smaller image works, that narrows the issue toward the original file or the resources needed to handle it. Logs are still needed to distinguish the underlying causes.
This is an illustrative scenario, not a diagnosis of every failed PNG upload.
Verify the Result Before Repeatedly Retrying
Check whether the file already appears in the Media Library. Open it, inspect the preview, and insert it into a draft.
Confirm that the original and required image sizes are usable. A file can transfer successfully while later processing fails.
Repeated attempts can leave duplicate or incomplete entries. Review them before deleting anything, especially if an attachment is already used in a published page.
What to Send Your Hosting Provider
A useful support request includes the exact error, timestamp and timezone, file format, size, dimensions, affected upload method, and results of the small-file test.
Include the failed request’s status and any relevant Site Health information. Ask support to check the matching application, PHP, web-server, and security logs.
These details give the investigation a specific starting point.
Frequently Asked Questions
1. Why does a small image upload while a large image fails?
Possible causes include request-size limits, processing resources, dimensions, or timeouts. Compare the files and inspect the error response before changing limits.
2. Does increasing the WordPress memory limit always fix uploads?
No. Memory is one possible constraint. It will not fix a disallowed format, missing temporary directory, full storage, or a request rejected before WordPress receives it.
3. Why does WordPress reject a file type?
The format may be disallowed, incorrectly identified, or unsupported by the relevant processing workflow. Multisite can also apply network-level upload restrictions. Check the file and applicable settings. Developer.WordPress.org
4. Should I upload images directly with SFTP?
Copying a file to a server does not by itself create a normal Media Library attachment with its metadata and generated sizes. Use the normal uploader or a supported import process after resolving the cause.
5. Should I change themes immediately?
Start with the file, error response, and comparisons above. Investigate the theme if evidence points to its upload-related code or editor behavior. Make disruptive tests on staging where possible.
Conclusion
Record the exact error and compare the failing file with a small, known-good upload. Then follow the evidence toward format support, effective limits, storage, permissions, or the upload workflow.
Retest after one controlled change and confirm the media works inside a page. If hosting support is needed, provide the failed request and timestamp so they can investigate the relevant logs.
