Quick Answer
WordPress media upload failure recovery should start by identifying whether the failed upload is a browser uploader problem, a file size limit, a blocked file type, a write-permission problem in wp-content/uploads, an image-processing dependency issue, a REST attachment request failure, or a storage/quota problem. The best fit is a small upload incident register: file name, file type, file size, upload route, visible error, current maximum upload size, Site Health media handling notes, uploads directory write state, attachment record state, public publishing hold, and owner for the next change. Choose the Browser Uploader when the multi-file uploader is the only failing surface. Choose host or filesystem review when Site Health says uploads or directories are not writable. Choose REST/API review when block editor media uploads fail but older admin upload paths behave differently.
Recovery Decision Table
| Signal | Better operator choice | Evidence to capture |
|---|---|---|
| One large file fails and smaller files upload | Check upload size, post size, and image-processing limits before changing content | File size, extension, max upload size, Site Health media handling note |
| Drag-and-drop upload fails, but Browser Uploader works | Treat it as an uploader-surface issue, not a storage outage | Browser, upload route, file name, success path |
| Every upload fails with a directory or permission message | Review wp-content/uploads writeability and owner path | Error text, current upload folder, recent deploy or migration |
| Media appears in the library but not in the post | Separate attachment creation from editor insertion or cache state | Attachment ID, post ID, editor action, public preview |
| REST media request returns 4xx or 5xx | Classify request status before retries or plugin changes | Status code, route, response type, security/cache layer |
| Existing images disappeared after upload work | Switch to missing-image recovery instead of more upload attempts | Affected URL, file URL, attachment record, backup note |
Who Should Use This Playbook?
Use this playbook when a WordPress publisher, editor-operator, site owner, agency maintainer, or small content team cannot upload an image, document, video, audio file, PDF, or other allowed media item during normal editorial work.
This is WordPress site-operations guidance, not legal advice, medical advice, financial advice, professional security consulting, accessibility certification, image-rights review, ranking advice, Google AdSense account guidance, Search Console account work, Bing account work, or a promise that media repair will improve traffic, indexing, approval, revenue, or monetization. It does not change WordPress settings, server permissions, plugins, themes, CDN rules, Google AdSense, Search Console, Bing Webmaster Tools, payment settings, tax settings, or production posts.
The operating risk is that an upload failure looks simple, so the operator retries, compresses files randomly, changes file permissions broadly, disables plugins, or publishes without the image. WordPress media documentation separates the Media Add New screen, Media Library, Media Settings, attachment behavior, Site Health media handling, and upload internals. A good recovery identifies which layer failed before changing the article, the media file, or the server.
This article is source-derived analysis from public WordPress and Google documentation. No private WordPress dashboard, Media Library, upload folder, wp-content directory, REST request, access log, host control panel, SFTP account, CDN account, Google AdSense account, Search Console property, Bing account, payment screen, tax setting, production URL, file archive, image asset, or user account was inspected for this article.
Step 1: Freeze The Editorial Decision
Do not keep retrying the same upload in the editor while the article deadline is under pressure. Repeated attempts can create duplicate attachment records, confusing filenames, partially attached media, or misleading evidence. First, define whether the content can wait, whether a placeholder is acceptable, and which file actually failed.
Use this incident register:
- [ ] Article title, post ID, author, and editor role.
- [ ] File name, extension, MIME type if known, file size, and pixel dimensions for images.
- [ ] Upload route: block editor, Media Add New, Media Library modal, Browser Uploader, REST integration, mobile app, or import tool.
- [ ] Exact visible error text and time.
- [ ] Whether smaller files or different file types can upload.
- [ ] Whether the file appears in Media Library after the failed attempt.
- [ ] Current maximum upload size shown by WordPress or Site Health.
- [ ] Recent changes: host migration, PHP change, plugin update, image plugin change, security rule, CDN rule, backup restore, permission change, or storage cleanup.
- [ ] Publishing decision on hold, such as schedule, social distribution, newsletter send, sitemap action, or source-note update.
Keep private evidence private. A public article can say what to capture. It should not expose admin URLs, filenames that identify customers, private images, user names, folder paths, raw logs, security plugin rules, account IDs, or screenshots of internal media assets.
Step 2: Compare Upload Surfaces
The WordPress Media Add New documentation describes the normal multi-file uploader and the Browser Uploader fallback. That distinction gives operators a clean first split. If one upload surface fails and another works, the site may not have a global media outage.
Use this surface check:
| Surface | What it can prove | What it cannot prove |
|---|---|---|
| Multi-file uploader | Normal dashboard upload path accepts the file | That editor insertion works |
| Browser Uploader | A simpler upload path can bypass some browser or script issues | That drag-and-drop is healthy |
| Media Library modal | Existing attachments can be selected or searched | That a new upload can be created |
| Block editor media block | Editor insertion and attachment selection work in context | That server storage is healthy |
| REST attachment request | API route and permission path can create or edit attachments | That the visual uploader is the problem |
Choose Browser Uploader when drag-and-drop or the multi-file uploader alone is failing. Choose Media Library review when the upload succeeds but the editor cannot find or insert the item. Choose REST/API review when editor uploads fail with a JSON, route, authentication, or response-class symptom.
Step 3: Check Size, Type, And Folder Rules Before Rewriting The Article
WordPress shows upload size information in media surfaces, and Site Health reports media handling details such as file uploads, maximum post data size, maximum upload file size, maximum effective file size, and image libraries. The Media Settings documentation also describes the year/month upload folder option and notes that WordPress creates those folders when wp-content is writable.
Use this triage:
| Evidence | Better choice | Common wrong move |
|---|---|---|
| File exceeds upload size | Resize or compress a copy, or route host limit review | Changing article copy to hide the missing media |
| File type is unexpected | Confirm allowed format and source purpose | Enabling broad unfiltered uploads |
| Year/month folder creation fails | Review writeability and deployment owner | Creating random public folders manually |
| Image processing fails after upload | Check image library and file dimensions | Re-uploading the same oversized source repeatedly |
| Storage or quota appears low | Pause media cleanup and confirm backup coverage | Deleting old media without attachment evidence |
Do not weaken file-type controls just to move one article forward. If the asset is required, create a smaller or approved-format derivative from the original source, preserve the source note privately, and keep the public article claim limited to what can be shown.
Step 4: Separate Attachment Creation From Article Placement
The Media Library documentation shows that WordPress stores details such as uploaded date, uploaded by, file name, file type, file size, dimensions, alt text, title, caption, description, file URL, and attachment relationship. That means an upload can partially succeed: the attachment record may exist even if the editor failed to insert it into the post.
Use this split:
- [ ] Search Media Library by file name and date before uploading again.
- [ ] Confirm whether the attachment has a usable preview or file URL.
- [ ] Check whether the item is attached to the expected post or is unattached.
- [ ] Record whether alt text, caption, title, and description still need editorial review.
- [ ] Confirm whether the post draft references the attachment or only has a failed placeholder block.
- [ ] Use public preview only after draft state and media state agree.
Choose wordpress-media-library-cleanup-checklist when the issue is duplicate or stale media inventory. Choose wordpress-missing-image-recovery-playbook when a previously published image no longer loads. Choose wordpress-image-optimization-checklist when the file is valid but too large for the page experience target.
Step 5: Use Site Health As A Routing Tool
Site Health should not replace direct upload evidence, but it is useful because it groups media handling, server, directory, and filesystem permission signals in one place. The best decision is to use Site Health as a routing tool, then confirm the failing layer with the narrowest evidence available.
Use this Site Health review:
| Site Health area | What to look for | Next article or owner |
|---|---|---|
| Media Handling | Uploads enabled, max sizes, image libraries, file count limits | Host or PHP owner |
| Directories and Sizes | Uploads directory location and size | Storage or backup owner |
| Filesystem Permissions | Whether WordPress can write to uploads and other directories | wordpress-file-permissions-checklist |
| Server | PHP limits, maximum upload file size, server details | Host support or deployment owner |
| WordPress Constants | Whether config changes affect file behavior | wordpress-debug-log-checklist or deploy owner |
Avoid turning this into a broad cleanup. If Site Health shows several unrelated notices, record them separately. The upload incident needs the smallest change that restores safe media creation and preserves editorial evidence.
Step 6: Classify REST And HTTP Failures
WordPress REST attachment code handles attachment routes, upload checks, file-size fields, and quota-style errors. WordPress upload handling also sanitizes filenames, checks extensions and MIME type, and moves files into the uploads directory. If an upload request returns a status code, classify the response before changing plugins or server rules.
Use this response taxonomy:
| Response class | Upload meaning | Recovery direction |
|---|---|---|
| 2xx with attachment data | Upload likely created a media item | Confirm Media Library and editor insertion |
| 3xx redirect | Upload request may be sent to login, HTTPS, or edge redirect | Review URL, session, proxy, and cache rules |
| 400 | Bad file, file too large, quota, or request shape may be involved | Check file, size, and REST error body |
| 401 or 403 | Session, permission, nonce, role, security plugin, or WAF may block upload | Review authenticated editor path |
| 404 | REST route, permalink, endpoint, or admin route may be missing | Pair with REST save failure recovery |
| 429 | Rate limiting may punish repeated attempts | Stop retries and review rule owner |
| 5xx | PHP, image library, storage, plugin, or host error may interrupt upload | Preserve logs and route to rollback or host review |
Google HTTP status documentation is useful here because 4xx, 5xx, redirect, and success classes have different downstream meanings for public URLs. For editor uploads, the same classification helps avoid a vague "WordPress is broken" diagnosis. A public homepage 200 does not prove that authenticated media uploads work.
Step 7: Decide The Smallest Safe Recovery
Once the layer is known, choose the smallest repair path.
| Failure class | Small recovery | Hold until |
|---|---|---|
| Browser uploader only | Use Browser Uploader for the urgent item and log browser evidence | Normal uploader cause has an owner |
| File too large | Upload an approved smaller derivative with source note | Page preview and image quality pass |
| Unsupported file type | Convert to an allowed format or link to an approved public source | File purpose and rights are clear |
| Upload directory not writable | Route to filesystem/host owner | Writeability and backup state are confirmed |
| Attachment created but not inserted | Insert existing Media Library item instead of re-uploading | Draft references the intended file |
| REST blocked | Review authenticated route, role, security, cache, or WAF layer | Response class changes and editor save works |
| Existing media missing | Stop upload work and use missing-image recovery | Public file and attachment state are known |
For a small publisher, the best fit is not a heroic server edit. It is a short evidence trail, one controlled change, and a post-recovery check that proves the article can be edited without creating hidden media debt.
What Evidence Should Stay Private?
Keep these details out of public article copy:
- Real admin URLs, user names, customer names, draft URLs, private filenames, unpublished images, and media source contracts.
- Raw server logs, REST nonces, cookies, security plugin rules, SFTP paths, host account IDs, CDN rules, and filesystem screenshots.
- Google AdSense account screens, Search Console ownership views, Bing account views, billing screens, payment settings, and tax settings.
- Claims that Yolkmeet tested a production upload, changed permissions, edited PHP settings, contacted a host, or inspected a real dashboard unless a future operator attaches private evidence and narrows the public wording.
Common Questions
Is a media upload failure the same as a missing image incident?
No. A media upload failure means WordPress could not create or place a new media item. A missing image incident means an existing public image, attachment record, file URL, or page reference no longer works. Use upload recovery for creation problems and missing-image recovery for already-published breakage.
Should I raise the upload limit immediately?
Not as the first move. Check the actual file size, maximum upload size, maximum post data size, image dimensions, file type, and editorial need. A smaller derivative may be the better choice for a content site, especially when the original asset is larger than the article needs.
Should I change file permissions to fix uploads?
Only with an owner and a backup path. Site Health and WordPress attachment guidance can point toward writeability issues, but public guidance should not tell operators to make broad permission changes blindly. Use wordpress-file-permissions-checklist when writeability is the confirmed failure class.
What should be checked after recovery?
Confirm that the intended media item exists once, has the expected file name and dimensions, includes editorial fields such as alt text when relevant, appears in the draft or published post, and loads in preview or public view according to the article state. Then record the source file, derivative choice, owner, and next review date.
Source Notes
- https://wordpress.org/documentation/article/media-add-new-screen/ checked 2026-06-22; used for source-derived analysis of Media Add New, multi-file upload, Browser Uploader fallback, progress display, maximum upload size messaging, and post-upload edit links.
- https://wordpress.org/documentation/article/media-library-screen/ checked 2026-06-22; used for source-derived analysis of attachment details, media search/filtering, uploaded-to relationships, file URL, file size, dimensions, alt text, captions, and delete risk.
- https://wordpress.org/documentation/article/settings-media-screen/ checked 2026-06-22; used for source-derived analysis of media settings, image sizes, upload folder organization, and automatic folder creation when
wp-contentis writable. - https://wordpress.org/documentation/article/use-image-and-file-attachments/ checked 2026-06-22; used for source-derived analysis of upload paths, attachment-to-post behavior, insertion choices, and
wp-contentpermission relevance. - https://wordpress.org/documentation/article/site-health-screen/ checked 2026-06-22; used for source-derived analysis of media handling, upload sizes, image libraries, directories, server settings, and filesystem permission signals.
- https://developer.wordpress.org/reference/functions/_wp_handle_upload/ checked 2026-06-22; used for source-derived analysis of WordPress upload handling, filename sanitation, MIME/extension checks, PHP upload data, and upload directory movement.
- https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/ checked 2026-06-22; used for source-derived analysis of REST attachment fields, upload size checks, quota errors, and attachment file metadata.
- https://developers.google.com/crawling/docs/troubleshooting/http-status-codes checked 2026-06-22; used for source-derived analysis of HTTP response classes when upload or media URLs return redirects, client errors, rate-limit responses, or server errors.
Internal Link Notes
Link to wordpress-media-library-cleanup-checklist when upload retries created duplicate or stale attachments. Link to wordpress-file-permissions-checklist when the evidence points to uploads directory writeability. Link to wordpress-missing-image-recovery-playbook when existing public media no longer loads. Link to wordpress-rest-api-save-failure-recovery-playbook when editor media uploads fail through a REST route. Link to wordpress-backup-restore-drill-playbook before deleting media or changing storage paths.
Update Notes
Review this playbook every 60 days. Recheck official WordPress Media Add New, Media Library, Media Settings, attachment, Site Health, upload handling, REST attachment, and Google HTTP status documentation before changing claims. Refresh earlier after a WordPress core release changes media upload behavior, Site Health media fields, REST attachment responses, allowed file handling, image library behavior, or Yolkmeet changes its image workflow, upload storage, backup policy, or editor handoff process.