When WordPress media upload fails, the public site may still look fine. The failure can be an HTTP error in the uploader, a file that lands in the library without a preview, a Media Library grid that never finishes loading, or images that work in Admin but break on the front end.
Work this checklist in order. Prefer staging when you can reproduce the upload there. Take a backup before changing file permissions, PHP limits, or security plugins on production. Once uploads and the library work again, restore any settings or plugins changed only for testing and recheck a normal image and a PDF if you use them. If one covered WordPress issue is clearly to blame and you want help, use the $99 one-time fix after you can authorize access.
Define what failed
- Note the exact message: HTTP error, “exceeds the maximum upload size,” “unable to create directory,” a spinning Media Library, or a blank/broken attachment page.
- Try a small JPEG under 500 KB and a second file type you normally use (PNG, WebP, or PDF). If only large files fail, start with size and memory limits.
- Confirm you can open Admin at all. If login or Admin is broken, fix that first with the admin login checklist.
- If the whole site shows a critical error, 403/500/502, or is offline, use the matching checklist before the Media Library: critical error, 403/500/502, or site down.
Quick triage map
| What you observe | Likely layer | First useful check |
|---|
| HTTP error on every upload | Server / PHP / security | Host error log for that minute; security or WAF rule on async-upload.php |
| File appears; no thumbnail / “scaled” missing | Image processing | GD or Imagick available; memory_limit; disk space under uploads |
| Library grid spins or shows empty tiles | Admin JS / REST / cache | Browser console; REST /wp/v2/media; disable script defer on Admin |
| “Unable to create directory” / permission denied | Filesystem | Ownership and modes on wp-content/uploads; free disk space |
| Upload works; front-end image 404 | URL / CDN / offload | Attachment URL vs real file path; CDN or offload plugin sync |
Safe triage order
- Confirm the upload path and disk. In Settings → Media, note the organized uploads setting. On the host, check that
wp-content/uploads (and the current year/month folder if used) exists, is writable by the web user, and has free disk space. Do not use 777 permissions. Ask your host to confirm the correct file ownership and permissions.
- Check PHP upload and memory limits. Compare the failing file size to
upload_max_filesize, post_max_size, and memory_limit (your hosting panel, Tools → Site Health → Info, or your host’s support team). post_max_size must be at least as large as upload_max_filesize. Raise limits with the host or an allowed config method; avoid random php.ini guesses on shared hosting.
- Read the matching log line. Retry one upload and open the web server or PHP error log for that timestamp. A denied path under
wp-admin/async-upload.php or admin-ajax.php points to a security rule. A memory or timeout line points to limits or a stuck image editor. Keep logs private—they can include paths and tokens.
- Test image processing. If the file saves but thumbnails never appear, confirm the host provides GD or Imagick for PHP, then retry a small JPEG. On staging, temporarily switch to an installed default WordPress theme and disable non-essential plugins one at a time, starting with security, image-optimization, and media-offload plugins. See also plugin not working when isolation points at one plugin.
- Repair a broken Media Library grid. Open the browser console on Media → Library (grid view). Failed REST calls, blocked admin-ajax, or script errors after a cache/minify plugin often break the grid while list view still works. Bypass page cache for Admin, disable script combine/defer for Admin if your cache plugin allows it, and retest. A security plugin that blocks REST for logged-in editors can produce empty tiles.
- Check URL and offload mismatches. Open a newly uploaded file’s attachment URL in a private window. If Admin shows the file but the URL 404s, check
siteurl/home, HTTPS mixed content, CDN purge, and any S3/Cloudinary/offload plugin that must sync or rewrite URLs. Fix the sync before regenerating every thumbnail site-wide.
- Retest the full media path. Upload a small image, confirm the thumbnail in the library, insert it into a draft post, and preview the post. Restore any temporary plugin or cache changes and retest once more.
Common causes
- File larger than PHP or host upload limits;
post_max_size smaller than upload_max_filesize.
uploads directory missing, owned by the wrong user, or on a full disk.- Security, WAF, or ModSecurity rules blocking multipart uploads to
async-upload.php.
- GD/Imagick missing or memory exhausted while generating intermediate sizes.
- Image optimization, WebP conversion, or media-offload plugins failing mid-upload.
- Admin scripts deferred/combined; REST API blocked for authenticated users; stale CDN on attachment URLs.
- Corrupt upload from a flaky network; retry with a smaller file before bulk changes.
When a $99 one-time fix fits
Request the $99 one-time WordPress fix if you want help with one clearly defined media issue on one WordPress site. Name the exact error text, file type and size, whether thumbnails fail, when it started, and the last change you made. We confirm the scope before work begins. Send credentials only through the private access link provided after your request is accepted.
Full rebuilds, new custom galleries, full migrations, account-wide host outages, and multiple unrelated issues are outside this offer. If a plugin update broke uploads along with other Admin features, see also plugin update broke WordPress site.
Related checks
If the checks do not identify the cause, send your host the exact error text, failing file type and size, timestamp, and any matching log lines (secrets redacted). Suspected compromise needs a security investigation as well as restoring uploads.