Que el archivo exista en disco no basta. WordPress guarda un adjunto, la ruta relativa y metadatos de tamaños; el servidor debe mapear después la URL solicitada hacia un archivo legible. Las migraciones suelen romper uno de esos enlaces.
Empieza por una imagen y sigue URL, metadatos y ruta antes de regenerar toda la biblioteca.
Conserva la petición fallida
Inspecciona el <img src> o URL CSS rota y solicítala directamente. Anota estado, redirecciones, tipo, cuerpo y cabeceras de caché o CDN.
Interpreta:
404 -> ruta o nombre no coincide
403 -> permisos, hotlink o seguridad
500 -> reescritura, PHP o transformación CDN
200 HTML -> ruta, caché o acceso incorrectos
SSL o contenido mixto -> protocolo o dominioNo publiques URLs de adjuntos privados.
Relaciona URL y sistema de archivos
Confirma URL y directorio base de subidas y la ruta esperada año/mes/archivo.ext. Consulta _wp_attached_file mediante APIs de WordPress.
$relative = get_post_meta( $attachment_id, '_wp_attached_file', true );Registra solo la ruta relativa de una imagen pública controlada. No edites metadatos serializados directamente.
Revisa mayúsculas: Image.jpg y image.jpg pueden funcionar en un host y diferir en Linux.
Verifica original y derivados
El original puede existir y faltar la miniatura solicitada. Revisa _wp_attachment_metadata y compara nombres y dimensiones.
No renombres archivos manualmente sin actualizar metadatos. Usa herramientas de regeneración en staging y lotes acotados en producción.
Conserva originales y comprueba disco e inodos.
Revisa URLs migradas
Busca el dominio antiguo, HTTP o rutas de staging en contenido, maquetadores, imágenes destacadas y CSS. Usa una sustitución compatible con serialización y primero en seco.
wp search-replace 'https://old.example' 'https://example.com' --all-tables-with-prefix --dry-runRevisa coincidencias y no cambies GUID o URLs externas firmadas a ciegas.
Inspecciona permisos y propiedad
El servidor necesita leer archivos y atravesar directorios superiores. Compara propietario y modo con una imagen que funcione.
Usa la reparación de cPanel, Plesk o proveedor. No apliques 777 ni hagas públicas subidas privadas.
Revisa ACL, protección hotlink y seguridad ante un 403.
Revisa offload, CDN y reescritura
Los plugins pueden enviar URLs a una CDN u object storage. Confirma que el objeto existe, que la política permite acceso y que la clave coincide en mayúsculas y ruta.
Prueba sin reescritura en staging si hay fallback local. No elimines originales remotos hasta validar toda la biblioteca.
Comprueba que Nginx o Apache no envíe medios reales a WordPress.
Gestiona nombres y codificación
Los nombres con acentos, espacios o Unicode pueden cambiar al transferirse. Compara bytes y nombres exactos entre origen y destino.
Prefiere un renombrado consciente de WordPress que actualice metadatos y referencias. No normalices en masa sin mapa y redirecciones.
Prueba ejemplos en inglés, español y catalán.
Trata archivos sin registros de adjunto
Una migración solo del sistema de archivos puede copiar imágenes y omitir sus entradas y metadatos. La URL directa funciona, pero no aparecen en Medios ni generan tamaños responsive.
Usa en staging una herramienta fiable para crear registros de una lista explícita. No registres miniaturas de caché como originales. Conserva fechas y rutas cuando proceda y detecta duplicados por checksum, no solo por nombre.
Revisa srcset y lazy loading
El src principal puede existir y faltar una opción de srcset, por lo que solo falla en ciertas pantallas. Comprueba qué candidato elige el navegador.
Revisa atributos lazy y scripts de sustitución. Un error JavaScript puede dejar placeholders aunque las URLs funcionen. Repara tamaños y marcado; no desactives globalmente imágenes responsive.
Verifica la integridad de medios
Prueba original, miniaturas, srcset, inserción del editor, destacada y CDN con caché caliente. Ejecuta una auditoría acotada de enlaces rotos.
El mantenimiento recurrente debe incluir subidas en las pruebas de migración y vigilar 4xx de imágenes. La reparación termina cuando base, disco y URL pública coinciden en archivos actuales y nuevos.