The Media Library shows images with missing thumbnails, blank alt text across hundreds of uploads, or attachment records that point to deleted files. A plugin update scrambles attachment metadata. Or a server migration breaks file paths. WordPress media alt repair and attachment metadata regeneration are the tools for restoring a broken media library to a correct, accessible state — whether the problem is missing alt text, broken image sizes, or orphaned database records. This fits into the wider topic we cover in our WordPress Errors Complete Guide.
WordPress Media Alt Repair — Regenerating Missing Alt Text
WordPress media alt repair for missing alt text addresses both the accessibility gap (images with no descriptive text for screen readers) and the SEO gap (images that search engines cannot contextualise). A site migrated from another platform, a bulk image import, or years of uploads without enforcing alt text standards leaves a media library where most images have no alt text.
Audit the gap first: WP-CLI provides the fastest count — wp post list --post_type=attachment --post_mime_type=image --fields=ID --format=count shows total images, then wp post list --post_type=attachment --post_mime_type=image --fields=ID --format=count --meta_query='[{"key":"_wp_attachment_image_alt","compare":"NOT EXISTS"}]' shows images with no alt text. The difference is the number of images that have alt text set. For a visual audit without WP-CLI: Media → Library → List view — the columns include a clickable image and title but no native alt text column. Install the Media Library Helper plugin to add an Alt Text column to the list view, making the audit visual without command-line access.
Bulk WordPress media alt repair using the image filename as a starting point: wp post list --post_type=attachment --post_mime_type=image --fields=ID,post_title --format=csv | tail -n +2 | while IFS=',' read id title; do current=$(wp post meta get $id _wp_attachment_image_alt 2>/dev/null); if [ -z "$current" ]; then wp post meta set $id _wp_attachment_image_alt "$title"; fi; done — this sets the alt text to the image’s WordPress title for any image that currently has no alt text. The title is not ideal final alt text but provides a descriptive starting point (WordPress titles default to the filename with hyphens replaced by spaces) that can be manually refined. After bulk setting title-based alt text, export a list of all images for editorial review and improvement: the bulk operation ensures every image has some alt text while the editorial review adds quality to the highest-priority images (those used in featured positions, in the first three posts, or in product listings where alt text quality directly affects conversion). According to the WordPress developer documentation, the _wp_attachment_image_alt meta key is the authoritative alt text storage location — setting or updating this meta key directly updates the alt text for all future uses of that image across all posts and pages without requiring any post-level edits.
Regenerating Attachment Metadata and Image Sizes
Attachment metadata covers dimensions, file paths, and thumbnails — WordPress media alt repair for these in the _wp_attachment_metadata post meta record. After a server migration, theme change (different registered image sizes), or plugin update that changes image size registrations, this metadata can become stale — thumbnails that do not exist, sizes that are wrong, or file paths that no longer match the server’s directory structure. WordPress media alt repair for these metadata issues requires regenerating the attachment metadata.
Regenerate All Thumbnails is the standard plugin for WordPress media alt repair: Media → Regen. Thumbnails → Regenerate All Thumbnails → the plugin processes every image attachment, generates any missing thumbnail sizes registered by the current theme and active plugins, and updates the attachment metadata with the correct file paths and dimensions. For large media libraries, this process runs in background batches — the admin shows progress and estimated completion time. Run thumbnail regeneration after: switching themes (new theme may register different image sizes), installing or removing image-handling plugins, or migrating servers where the uploads directory path changed.
WP-CLI provides faster thumbnail regeneration for large libraries: wp media regenerate --yes processes all images in the background without timeout concerns that can interrupt the plugin’s browser-based progress display on large libraries. Add --only-missing to regenerate only thumbnails that do not already exist rather than recreating all sizes — significantly faster for partial updates. For targeted WordPress media alt repair of specific images: wp media regenerate 12345 67890 regenerates only the specified attachment IDs. The targeted approach is useful when debugging specific broken images rather than running a full library regeneration. After regeneration, clear all caches — a caching plugin that serves cached image URLs pointing to the old file paths will continue serving broken images until the cache is cleared and rebuilt with the correct URLs from the regenerated metadata. Our guide on fixing WordPress images not displaying covers the file permission and URL configuration issues that must be correct before thumbnail regeneration can create the image files in the correct server location.
Fixing Orphaned Media and Broken Attachment Records
Orphaned database records are a distinct WordPress media alt repair scenario — attachment posts in wp_posts that reference files that no longer exist on the server — requires identifying and resolving the mismatches between the database and the filesystem.
Orphaned attachment records need WordPress media alt repair to match database to filesystem: the Media Library Cleaner plugin scans the media library and identifies attachment records whose referenced files are missing from the uploads directory. These orphaned records waste database space and produce 404 errors when WordPress tries to serve the attachment URL. The plugin shows a list of orphaned records and provides bulk delete to clean them. Before deleting, export the list with the referenced file paths — some orphaned records may indicate files that should be recovered from a backup rather than deleted.
Orphaned files in the uploads directory (files with no corresponding database record) are the opposite problem — files uploaded to the server outside of WordPress’s media library system, or files left over after their attachment records were deleted. These orphaned files waste disk space but do not cause errors. Media Library Cleaner identifies these as well. For large cleanup operations involving thousands of orphaned files, WP-CLI combined with a custom PHP script provides more control than the plugin’s interface — filter by file type, date range, or directory before deleting to ensure only genuinely orphaned files are removed. For any WordPress media alt repair involving file deletion, always verify using a staging environment first and maintain a recent full backup before running bulk delete operations on media files that cannot be recovered without the backup. Our guide on setting up WordPress backups covers the backup strategy that provides the safety net needed before running any bulk media library cleanup or repair operation.
Repairing Media After Site Migration
Site migrations are the most common trigger for WordPress media alt repair needs — moving from one host to another, changing the domain, or moving from HTTP to HTTPS changes the base URLs of all media files stored in post content and attachment records.
The search-and-replace operation for media URLs: Better Search Replace plugin → Database → select all tables → Search for the old domain or URL (https://old-domain.com/wp-content/uploads/) → Replace with the new URL (https://new-domain.com/wp-content/uploads/) → Run Search & Replace. This updates all hardcoded media URLs in post content, widget settings, and other database-stored HTML. WP-CLI’s equivalent: wp search-replace 'https://old-domain.com' 'https://new-domain.com' --all-tables. After the search-and-replace, flush all caches and verify that media files load correctly on the front-end. Check the attachment metadata (_wp_attachment_metadata) to ensure the file paths stored there also updated correctly — some serialised metadata may require a second targeted search-and-replace if the initial run missed the serialised format.
HTTP to HTTPS migration for media requires the same search-and-replace but also a server-level redirect to ensure the old HTTP media URLs (which may be saved in external sites’ HTML or cached by CDNs) redirect to the HTTPS versions. Without the redirect, external embeds of the media files continue requesting HTTP versions after the migration, either producing mixed content warnings or serving broken images from CDN caches that still have the HTTP versions. For WordPress media alt repair specifically after an HTTP to HTTPS migration: alt text is stored separately from the file URL (in the _wp_attachment_image_alt meta key) and is not affected by the URL change — the alt text repair work from pre-migration remains intact. Only the file URLs and any hardcoded references in post content need the search-and-replace treatment. Reviews from the WordPress support community confirm that running Regenerate All Thumbnails after every server migration and running Better Search Replace for the domain change together resolve the vast majority of media-related WordPress media alt repair needs that arise from site migrations, without requiring manual inspection of individual attachment records. Our guide on WordPress import export and site migration covers the complete migration workflow that includes media URL repair as one of the final verification steps after moving a WordPress site to a new host or domain.
Image format conversion as part of WordPress media alt repair addresses the performance and compatibility issues that accumulate in media libraries with mixed image format quality — PNG files that should be JPEG for photographic content, or older JPEG files that should be converted to WebP for browser-supported compression efficiency. The Imagify, ShortPixel, and Smush plugins provide bulk image optimisation and format conversion: process the entire media library to convert oversized PNG photos to optimised JPEG or WebP, reducing file sizes by 40–80% without visible quality loss. Format conversion creates new optimised files alongside the originals — WordPress serves the optimised versions while the originals remain available as the source for regeneration if the conversion settings need to be changed. For WordPress media alt repair that includes format modernisation, run thumbnail regeneration after format conversion to ensure all generated sizes also use the optimised format rather than inheriting the original format for generated thumbnails.
Accessibility auditing as the final step of WordPress media alt repair confirms that the alt text added during the repair process meets WCAG standards and is genuinely useful to screen reader users. The WAVE browser extension (by WebAIM, free) inspects any WordPress page and flags images with empty alt text (requiring description), images with alt text that is suspicious (just “image”, the filename, or very short generic text), and images with excessively long alt text (over 250 characters, which becomes verbose for screen reader users). Run WAVE on the homepage, a representative blog post, and any product pages after completing the alt text repair to verify the quality of the added descriptions. The accessibility audit serves a dual purpose: confirming the WordPress media alt repair work is complete and flagging any low-quality alt text added during the bulk repair that requires editorial improvement before the images provide genuine accessibility value to visitors using assistive technology.
CDN and caching interaction with WordPress media alt repair operations requires careful sequencing — CDN caches store the original broken versions of media files and return them to visitors even after the underlying files are repaired. After completing any media repair involving thumbnail regeneration, URL changes, or file path corrections: purge the CDN cache completely (Cloudflare → Cache → Purge Everything, or the hosting CDN’s equivalent) and clear all WordPress-level caches (caching plugin → Empty Cache). The CDN purge forces all edge nodes to fetch fresh versions from the origin server, ensuring visitors see the repaired media files rather than the cached broken versions. For media URL changes specifically (HTTP to HTTPS, domain change), also purge the CDN’s image-specific cache if the CDN serves images from a separate image optimisation layer — some CDN configurations cache media files independently of HTML pages, requiring a separate targeted purge for the /wp-content/uploads/ path to ensure all media URLs are refreshed alongside the page caches. Our guide on WordPress caching covers the full cache clearing workflow including CDN purge that applies as the final step after any significant WordPress media alt repair operation that changes files or URLs in the media library.
Preventive WordPress media alt repair is more efficient than reactive bulk repair — establishing workflow rules that require alt text at upload time eliminates the accumulation of images needing repair. Enforce alt text at upload: add a custom validation hook that displays an admin notice when a new image is uploaded without alt text. The media_row_actions filter can add a prominent “Missing Alt Text” indicator to the Media Library list view for any image missing the _wp_attachment_image_alt meta key. For editorial teams, integrating alt text into the image upload checklist — alongside attribution, file naming, and compression — creates a quality gate that prevents the media library from accumulating accessibility gaps that later require bulk repair. The investment in preventive workflow is proportional to library size: a site adding 10 images per week that requires WordPress media alt repair on 500 accumulated images every year would instead spend 30 seconds per image at upload time — roughly the same total effort but distributed preventively rather than concentrated in disruptive repair sessions.
