wp_delete_media: delete media
Removes an attachment. The least recoverable write in the WordPress groups, and the one to be most reluctant about.
Arguments
| Argument | Required | Meaning |
|---|---|---|
id |
Yes | The attachment ID |
force |
No | Skip the trash |
dry_run |
No | Report without deleting |
Permissions
Allow content writes open, and delete_post on the attachment.
Deleting media is not like deleting a post
A deleted post goes to the trash and can be restored from the WordPress admin. Media does not behave the same way in practice: WordPress trashes attachments only when media trash is explicitly enabled on the site, and most installations do not enable it.
On a typical site, deleting an attachment removes the record and the files from disk — the original and every generated size. There is no restore, and recovery means a backup of both the database and the uploads directory.
Treat every media deletion as permanent unless you have specifically confirmed otherwise on that site.
Nothing tells you where it was used
This is the real hazard. WordPress does not track which posts, pages, builder layouts, theme settings, widgets or product galleries reference an attachment, and neither does this tool.
Deleting an image that is in use produces broken images wherever it appeared, discovered later by a visitor rather than immediately by you.
Before deleting, establish where it is used — and no MCP tool can do that for you. Check the WordPress admin's media details, search content for the filename, or use a plugin built for the job.
If you cannot establish that an attachment is unused, do not delete it.
Always dry run
dry_run returns the ID it would delete, and nothing else — not the record.
That is thin, so pair it with a read:
Read media 1180 and show me its title and URL. Then use a dry run for the deletion.
Confirming the URL is what tells you which image is about to disappear.
What it returns
deleted and the id. Not the record — read it first if you want it noted anywhere.
Never delegate the criterion
Name the IDs:
Delete media 1180 and 1181. Nothing else.
Not "delete the unused images". An assistant cannot determine what is unused, so that instruction asks it to guess, with an irreversible operation and no way to check its work.
This is the clearest case in the documentation where a plural, criterion-based instruction should simply be refused.
Alternatives worth preferring
- Leave it. Unused attachments cost disk space and nothing else. Disk is cheaper than a broken hero image on a service page.
- Replace instead of deleting. POM AI's own image tools can replace an attachment and rewrite references across the site — a different operation with a different safety story. See Replace an image everywhere it appears.
- Do a real audit with a plugin that maps usage, then delete from the WordPress admin where you can see the consequences.
After deleting
- Check the pages the image was on, if you know them.
- Check archive and listing pages.
- Purge the cache — a cached page can keep showing an image whose file is gone, which delays the discovery.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_forbidden |
No delete_post on the attachment |
| Broken images appeared | The attachment was still referenced |
| It cannot be restored | Media trash is not enabled on most sites |
| A page still shows the image | Cached; the file is already gone |
Related
wp_get_media_item— read before deleting- Replace the original or create a new attachment
- Recover from a failed write