Starting a website?

Purpose-Built Templates

ZU2B Blueprints

Business in a Box

Reference

ZU2B Pulse™

See what visitors experience before they leave — paste any public URL and get a plain-English performance report in seconds.

Scan Your URL Free
FAQ • Support
,

The Silent Rename That Breaks Your CSS

Field Note #107
🔬 Generalized 🟢 Beginner ⏱ 30 Minutes ✓ Observation from Experience
You upload a photo. It looks fine. Weeks later, a CSS rule that was working perfectly suddenly stops applying to that exact image — and nothing about your CSS changed. The most likely explanation has nothing to do with the stylesheet at all: WordPress quietly renamed the file the moment you uploaded it.

Why this happens
If you upload an image larger than roughly 2560px on its longest edge, WordPress automatically scales it down for storage efficiency — and appends -scaled to the filename when it does. A file named hero-photo.jpg silently becomes hero-photo-scaled.jpg behind the scenes.
Normally this is invisible and harmless. It becomes a real problem the moment your CSS targets that image by a class tied to its WordPress attachment ID or filename pattern — a common technique for styling a specific Cover block background, for example:
.wp-block-cover:has(img.wp-image-7402) { /* custom styling */ }
If you ever delete that image and re-upload a replacement — even one with the exact same filename and purpose — WordPress assigns it a brand new attachment ID. Your CSS selector, still pointing at the old ID, now matches nothing. The image displays fine; your custom styling just silently stops applying, with no error anywhere to tell you why.

How to confirm it
Right-click the image on your live page → Inspect, and look for a class like wp-image-XXXX in its HTML. Compare that number to whatever ID your CSS selector references. If they don’t match, that’s the whole bug — found in about ten seconds once you know to look for it.

The fix
Update your CSS selector to the image’s current ID. If you expect to swap this particular image out again in the future, consider a more durable selector that doesn’t depend on the ID at all — targeting the block’s position, a custom class you add by hand in the block’s “Additional CSS Class(es)” field, or a data attribute you control yourself.

How to avoid it next time
Two habits prevent this bug entirely:
Pre-resize images before uploading, keeping them under roughly 2560px on the longest edge. This sidesteps the auto-scaling (and the rename) altogether — you’ll also get a smaller file size and faster page load as a bonus.
Avoid ID-based CSS selectors for anything you expect to update later. A custom class you set yourself (.my-hero-image) survives a re-upload; a WordPress-generated wp-image-XXXX class does not, since that number is tied to one specific upload, not the “concept” of that image slot.

Tagged in :

,

More from the field