wp_set_featured_image: set a featured image

Assigns an attachment as a post's featured image, or removes the one it has.

Arguments

Argument Required Meaning
post_id Yes The post or page to change
media_id No The attachment to assign; omit it to remove
dry_run No Report without writing

That is the whole removal mechanism — there is no separate tool and no explicit "remove" flag. Calling with only post_id deletes the post's featured image and returns a thumbnail_id of 0.

It is worth stating plainly because it is easy to trigger by accident. A client that builds the arguments and drops media_id — because a lookup returned nothing, or a variable was empty — removes the image rather than failing.

If you are assigning, confirm the response's thumbnail_id is the ID you expected and not 0.

Permissions and target validation

The content write gate and permission to edit the target post are required. The target must be a supported content type. A nonzero media_id must identify a readable image attachment on this site; an ordinary post, non-image attachment or negative ID is refused before approval. File availability and rendered crop still need visual verification.

The post type must support thumbnails

If the target post type does not declare thumbnail support, the assignment is stored but nothing displays it.

Check with wp_get_post_types, whose supports list answers this directly.

What it returns

The post_id and the resulting thumbnail_id. Reading that back is the confirmation — 0 means the image was removed.

The preview reports the current thumbnail and the requested replacement without writing, which is a cheap way to confirm the arguments were built as intended.

Size still matters

Assigning an image does not resize it. WordPress renders the featured image at whatever size the theme asks for, generated from the original — so a small original produces a soft or undersized hero.

The tools report no dimensions, so open the attachment's url and look before assigning it to a prominent slot. See wp_get_media_item.

After assigning

  • Open the post on the front end and check the image appears at the right crop.
  • Check any archive or listing page, which often uses a different generated size.
  • Purge the cache.

Using it well

Set media 1180 as the featured image for post 412, then read the post back.

To remove:

Remove the featured image from post 412.

For several posts, name the pairs explicitly rather than describing a rule:

Set 1180 on post 412, and 1181 on post 415. Nothing else.

Common problems

Symptom Cause
The write is refused Content write gate closed
pom_ai_mcp_forbidden No edit_post on the target post
The featured image was removed media_id was omitted or empty
Nothing displays The post type lacks thumbnail support, or the theme does not show it
A broken image The attachment record exists but the file does not
The image looks soft The original is smaller than the display size
Review AI wine data
Previous
`wp_update_media`: update media metadata
Next