Prevent Duplicate WordPress Images During Profile Sync

If a profile sync downloads the same photo on every run, clearing the Media Library will not solve the underlying problem. The importer needs a reliable way to recognize an image it already imported. In staff and location syncs, I used source metadata to connect each remote asset with its local attachment. An unchanged image could then be reused, while a changed or missing file followed an explicit replacement path. Only after repeated runs stopped creating new duplicates did cleanup become worthwhile. Existing attachments still needed reference checks because an older photo could be used elsewhere on the site.

Identify the source asset beyond its filename

Remote URLs can contain query signatures, resized variants, or generic names such as profile.jpg. Two different people may share a filename, and one person’s URL may change without the bytes changing. Basename matching could both merge unrelated assets and duplicate equivalent ones.

I created explicit source metadata that records the remote owner, source URL or stable asset key, and a content signal where available. Matching became a documented service instead of a guess inside two separate syncers.

Find an existing attachment before downloading

The media service first looks for an attachment already linked to the remote identity. If the source has not materially changed and the file is healthy, it reuses that attachment. If the source changed, it imports a replacement, updates the profile relationship, and records the new state.

A retry after a timeout follows the same path. It does not create a second image merely because the first request failed after WordPress had already inserted the attachment.

Share the same media rules across sync features

Staff and location profiles originally carried their own media logic. Small differences in URL normalization and attachment lookup produced inconsistent behavior. I moved identity, download validation, reuse, replacement, and metadata into one module, then made both syncers call it.

The code change removed old logic as well as adding new code. Using one implementation prevented the staff and location syncs from applying different matching rules.

Check references before cleaning up duplicates

After repeated imports stopped creating duplicates, I could identify historical duplicates. Even then, “same source” did not automatically mean “safe to delete.” An attachment may be used in post content, as another featured image, or by a field the sync does not own.

The cleanup tool reports candidates, references, and the attachment selected to keep. Destructive removal remains explicit and bounded. It does not scan the entire library and delete by filename.

Report fetch, validation, and replacement failures separately

• Remote image unavailable: keep the valid current attachment and report the fetch failure.
• Unsupported or oversized file: reject it without changing profile identity.
• Attachment missing on disk: repair or replace through the known source.
• Profile removed: apply retention policy instead of assuming its media is orphaned.
• Source image changed: replace deliberately and preserve audit context.

These outcomes give operators more than a generic “media error.”

Content hashes can help, but they are not the sole identity. Two profiles may intentionally use the same corporate placeholder, and one remote asset may be served in different encodings or compression levels. I use hashes as a comparison signal within a known source relationship, not as permission to globally merge every matching byte sequence in WordPress.

I also had to bypass or coordinate image optimization during sync. An optimizer can create derivatives, rewrite files, or add asynchronous work while the synchronizer is deciding whether an import completed. The media service records the original source relationship first and lets optimization remain an independent post-processing concern. Retries then check the stored WordPress records instead of assuming an external optimizer’s timing.

Backup and restore scenarios complete the identity model. A restored database may reference attachments whose files are absent, while a copied uploads directory may contain files unknown to the database. Repair logic verifies both attachment records and disk state before declaring a source reusable.

The operator report now separates reused, downloaded, replaced, skipped, and failed media. Those counts expose regressions quickly: an unchanged feed that suddenly downloads every image is a warning even if the final pages look correct. The report makes it possible to verify that repeated runs are reusing images.

Finally, I documented which system owns alt text and captions. Reusing an attachment is only correct if the destination’s editorial metadata should persist; replacing it blindly from the feed can erase accessibility work. Asset identity and descriptive content are related, but their ownership may differ.

Those ownership rules now travel with the shared media service instead of being rediscovered by each sync feature.

Verify reuse on repeated runs

Run an unchanged feed twice and compare the attachment IDs and media outcomes. The second run should reuse healthy files. Then test a changed source image, a timeout after creation, a missing local file, and an unavailable remote URL. Preserve useful existing attachments when a fetch fails. For historical cleanup, report candidate duplicates and their references before removal. Keep alt text and captions under documented ownership so media reuse also preserves the editorial work attached to each image.

Photo by Pixabay on Pexels.