Mediabibliotheek toont geen afbeeldingen in WordPress

Je opent de mediabibliotheek in wp-admin, je verwacht een wand vol thumbnails, en in plaats daarvan zie je een raster met grijze tegels, gebroken-afbeelding-iconen of generieke bestandsplaceholders. De bestanden staan nog op de server. De bibliotheek-entries staan nog in de database. Tussen die twee zit iets stuk en WordPress vertelt niet wat.

De reden dat het lastig te diagnosticeren is, is dat de mediabibliotheek geen één systeem is. Het is een database-tabel, een map met bestanden, een image library aan de PHP-kant, een JavaScript-grid dat thumbnails over HTTP laadt, en een geserialiseerde post meta-blob die het allemaal aan elkaar knoopt. Elk van die lagen kan stuk gaan op een manier die in de grid-view dezelfde melding oplevert, en de juiste fix hangt af van welke laag het is. Dit artikel loopt de zeven oorzaken langs die ik bij echte incidenten zie, op volgorde van hoe vaak ik ze tegenkom, met per oorzaak een check die niets stukmaakt voordat je naar de regenerate-thumbnails-knop grijpt.

Wat de bibliotheek toont versus wat er op schijf staat

Voordat je iets aanpast, moet je weten welke kant van de relatie stuk is. De grid-view van de mediabibliotheek doet drie dingen bij elke pagina-load: een query op wp_posts voor rijen waar post_type = 'attachment', het uitlezen van _wp_attached_file post meta om het relatieve pad van elk bestand op te zoeken, en het laden van de thumbnail-URL die op basis van dat pad wordt gebouwd. Loopt één van die drie stappen leeg, dan toont het grid een placeholder.

Twee checks vertellen je welke laag het is. Eerst: klik een attachment aan om het detailpaneel te openen. Zie je daar wel een werkende preview maar in het grid een gebroken tegel, dan bestaat het bestand en werkt de URL, en zit de fout in de thumbnail-URL die het grid bouwt (meestal mixed content, de -scaled-val, of een ontbrekende sub-size). Tweede check: open het WordPress Site Health-scherm onder Gereedschap: Sitediagnose: Info: Mediabeheer. Dat paneel laat zien welke image library actief is, welke formaten die ondersteunt en welk uploads-pad WordPress gebruikt. De twee checks samen sluiten in een minuut drie of vier oorzaken uit.

Zie je in geen van de twee een afbeelding, maar staat het bestand nog wel op schijf onder wp-content/uploads/2026/04/, dan is de link tussen database en bestand stuk: de post meta wijst naar het verkeerde pad, de rechten blokkeren de webserver, of de URL die de database aan de browser geeft is niet meer bereikbaar.

Oorzaak 1: bestandsrechten op wp-content/uploads

Dit is veruit de meest voorkomende oorzaak op hosts waar de eigenaar is gewisseld of waar iemand handmatig bestanden over SFTP heeft binnengekopieerd. Het bestand staat er. WordPress weet ervan. Maar de webserver-user (www-data, apache of nginx, afhankelijk van de stack) kan het niet lezen, dus de browser krijgt een 403 of een verbroken verbinding waar de JPEG had moeten zitten.

Het canonieke rechten-schema staat op developer.wordpress.org bij file permissions: mappen zijn 755 (of 750), bestanden 644 (of 640), en wp-config.php is 440 of 400. Diezelfde pagina is expliciet dat 777 een beveiligingsrisico is en niet de oplossing waar je naar moet grijpen. De volledige procedure voor het zetten en verifiëren van rechten over wp-content staat in mijn artikel over WordPress-bestandsrechten.

Voor de mediabibliotheek is de diagnose klein. Open de URL van een gebroken thumbnail rechtstreeks in een nieuw tabblad (rechtsklik op de placeholder, kopieer de afbeeldings-URL, plak). Je ziet één van drie dingen:

• Een 403 Forbidden bevestigt een rechten- of eigenaarsprobleem. De webserver-user kan het bestand niet lezen.
• Een 404 Not Found betekent dat het bestand niet staat waar de database denkt dat het staat. Door naar oorzaak 3.
• De afbeelding laadt netjes. Het bestand is in orde, het grid faalt om een andere reden. Door naar oorzaak 4 of 6.

Zag je de 403? Log dan in via SFTP of de bestandsbeheerder van je host en check de eigenaar en rechten op wp-content/uploads. De eigenaar moet matchen met de user waar PHP-FPM onder draait (zichtbaar onderaan het Site Health "Server"-paneel). Je weet dat de fix werkt zodra de gebroken thumbnail-URL als 200 terugkomt in het netwerktabblad en het grid bij de volgende pagina-load weer thumbnails toont.

Oorzaak 2: GD of Imagick ontbreekt of kan het formaat niet decoderen

Site Health is de autoritatieve bron voor welke image library WordPress gebruikt. Open Gereedschap: Sitediagnose: Info: Mediabeheer en kijk naar de actieve editor. WordPress geeft de voorkeur aan Imagick boven GD, maar op shared hosting waar Imagick is uitgezet valt het stilletjes terug op GD. Hetzelfde paneel laat de formaten zien die de actieve library kan verwerken.

Dat is belangrijk omdat sub-sizes worden gegenereerd op het moment van upload, niet on the fly. Upload je een AVIF-bestand naar een WordPress 6.5-site waarvan GD zonder AVIF-ondersteuning is gecompileerd, dan accepteert WordPress de upload, slaat het bestand op, maar genereert geen sub-sizes. Het resultaat is een bibliotheek-entry met een original_image en nul thumbnails, en het grid rendert dat als een placeholder.

Formaatondersteuning per versie, geverifieerd tegen de WordPress core dev posts:

• WebP: native upload en sub-size-generatie sinds WordPress 5.8. De actieve image library moet WebP nog steeds ondersteunen, wat Imagick al jaren doet en GD sinds PHP 5.4 (compile flag --with-webp). Lossless WebP-encoding in GD vereist PHP 8.1.
• AVIF: native upload en sub-size-generatie sinds WordPress 6.5 "Regina", uitgebracht op 2 april 2024. Voor GD vereist AVIF PHP 8.1+ gecompileerd met --with-avif en libavif 0.8.2 of nieuwer. Voor Imagick een recente ImageMagick-build met de AVIF-codec.
• HEIC: automatische conversie naar JPEG sinds WordPress 6.7. Vereist Imagick met HEIC-ondersteuning; GD doet überhaupt geen HEIC.

Laat Site Health zien dat de actieve library jouw geüploade formaat niet ondersteunt? Dan ligt de fix aan de serverkant, niet in WordPress. Op managed hosting open je een ticket met het verzoek de codec aan te zetten. Op een self-managed VPS installeer je de juiste system library (libavif, libheif) en herbouw je de PHP-extensie, of wissel je de actieve editor. Je weet dat de fix gelukt is zodra Site Health het formaat noemt onder Mediabeheer en een verse upload van datzelfde formaat sub-sizes genereert die in het grid verschijnen.

Een tweede variant op deze oorzaak is Imagick die wel geïnstalleerd is maar door ImageMagicks policy.xml op slot zit, waardoor bepaalde formaten stilletjes worden geweigerd. Op shared hosting kun je policy.xml niet zelf aanpassen, maar je kunt verifiëren door een bekende JPEG te uploaden en te kijken of er sub-sizes ontstaan. Doen ze dat? Dan leeft Imagick wel en is het probleem formaatspecifiek.

Oorzaak 3: post meta die niet meer klopt na een migratie

Als je een WordPress-site verhuist tussen hosts en wp-content/uploads los van de database overzet, eindig je makkelijk met paden die niet matchen. De database denkt dat het bestand op 2026/03/photo.jpg staat, maar het bestand is op 2026/04/photo.jpg geland, of in een submap die de migratietool eraan heeft toegevoegd, of met een andere bestandsnaam omdat de doel-filesystem hoofdlettergevoelig is en de bron niet.

Het autoritatieve gegeven is de _wp_attached_file post meta key op elke attachment-rij in wp_postmeta. Die slaat het pad relatief op ten opzichte van de uploads-basis, niet de volledige URL. WordPress combineert die waarde met wp_upload_dir()['baseurl'] op runtime om de thumbnail-URL te bouwen. Komt het relatieve pad niet meer overeen met een echt bestand, dan toont het grid een placeholder en laat de detailpagina van het attachment een gebroken preview zien.

Om één specifieke attachment te checken, open je de bewerkpagina in wp-admin en kijk je naar de URL onder "Bestands-URL". Bezoek die URL in een nieuw tabblad. Krijg je een 404, dan klopt de post meta niet of mist het bestand. Voor een check op schaal draai je WP-CLI:

# WP-CLI 2.10, draai vanuit de WordPress-root
wp post meta list --post_type=attachment --keys=_wp_attached_file --format=csv \
  | head -20

De verwachte output is een CSV met één rij per attachment, waarbij elke rij het relatieve pad toont dat de database voor dat bestand heeft. Spot-check een handvol tegen ls wp-content/uploads/2026/04/ en je ziet de mismatch meteen.

De fix als de bestanden in de verkeerde map staan is om ze terug te zetten waar de database ze verwacht. De fix als de database fout zit is een search-replace op de waardes van _wp_attached_file, waarvoor dezelfde tooling geldt die ik behandel in mijn artikel over WordPress search-replace database URL. Gebruik wp search-replace in plaats van een SQL REPLACE, want de post meta waardes zitten ook in geserialiseerde arrays in de bijbehorende _wp_attachment_metadata key, en een naïeve SQL-update sloopt die serialisatie.

Je weet dat de fix werkt zodra de gebroken thumbnail-URL's 200 retourneren, het grid weer thumbnails laat zien, en wp media regenerate --only-missing (zie oorzaak 4) nul fouten meldt.

Oorzaak 4: theme-wissel zonder thumbnails te regenereren

WordPress genereert image sub-sizes op het moment van uploaden, op basis van de sizes die op dat moment geregistreerd zijn. De functie die een size registreert, add_image_size(), definieert alleen een size; ze produceert geen bestanden voor media die er al staan. Wissel je van een theme dat een featured-large op 1200x600 had naar één dat een card-hero op 800x450 verwacht, dan heeft geen van je bestaande attachments een card-hero sub-size op schijf staan. Het grid toont de ontbrekende sub-size als placeholder en valt terug op wat het wel kan vinden.

De diagnose is om in de _wp_attachment_metadata-array van één attachment te kijken en de sizes-keys te vergelijken met de sizes die het actieve theme verwacht. De fix is sub-sizes regenereren voor de bestaande media.

De meest toegankelijke tool is de Regenerate Thumbnails-plugin. Installeer hem via Plugins: Nieuwe plugin, activeer hem en ga naar Gereedschap: Regenerate Thumbnails. Vink "Skip regenerating existing correctly-sized thumbnails" aan en klik op de regenerate-knop. De plugin toont een voortgangsbalk en een log per attachment.

Zowel deze plugin als het CLI-equivalent hebben dezelfde harde grenzen die het waard zijn om te kennen voordat je ze draait: ze regenereren vanuit het bestaande originele bestand, dus als het origineel mist falen ze; ze repareren geen database-corruptie (oorzaak 3); ze repareren geen rechten (oorzaak 1); en ze fixen geen mixed content (oorzaak 5). Los de onderliggende oorzaak eerst op, regenereer dan.

Heb je SSH-toegang? Het wp media regenerate WP-CLI-commando met de --only-missing-vlag doet hetzelfde vanaf de commandline en is sneller op sites met duizenden attachments:

# WP-CLI 2.10
wp media regenerate --only-missing --yes

De verwachte output is één regel per attachment, eindigend op Success: Regenerated X of Y images.. De --only-missing-vlag is het verschil tussen een regeneratie van vijf minuten en eentje van vijf uur bij een grote mediabibliotheek.

Je weet dat de fix gelukt is zodra het grid weer thumbnails laat zien en de regeneratie nul fouten rapporteert.

Oorzaak 5: HTTP-image-URL's na een SSL-migratie

Heb je een site verhuisd van http:// naar https:// en toont de mediabibliotheek nu lege tegels in de grid-view maar wel een werkende preview in het detailpaneel? Dan is de oorzaak mixed content. WordPress bouwt thumbnail-URL's op basis van siteurl en home in wp_options. Beginnen die waardes na de SSL-omschakeling nog steeds met http://, dan laadt het JavaScript-grid thumbnails over HTTP vanaf een HTTPS-adminpagina, en moderne browsers blokkeren die requests stilletjes als mixed content. De detailweergave werkt vaak wel omdat die de URL's anders bouwt en soms protocol-relatieve paden gebruikt.

De twee faalmodi die op WordPress core trac als #33092 en #34109 staan gedocumenteerd, bevestigen het verschil tussen grid en lijstweergave: met FORCE_SSL_ADMIN aan en siteurl nog op HTTP, geeft de AJAX-respons die het grid vult HTTP-URL's terug die de pagina afwijst.

De diagnose loopt in twee stappen. Eerst: in Instellingen: Algemeen check je dat zowel WordPress-adres (URL) als Site-adres (URL) met https:// beginnen. Doen ze dat niet, fix dat eerst. Tweede stap: open de gebroken grid-view, F12 voor je developer tools, switch naar de Console-tab, en zoek naar meldingen als "Mixed Content: The page at 'https://yoursite.nl/wp-admin/upload.php' was loaded over HTTPS, but requested an insecure element". Elke geblokkeerde request is een thumbnail.

De fix bestaat uit twee delen. Update siteurl en home naar HTTPS in Instellingen: Algemeen. Draai daarna een search-replace door de database om alle resterende http://yoursite.nl-verwijzingen in post-content, post meta en geserialiseerde opties te vangen. De procedure staat in mijn artikel over WordPress search-replace database URL, en het bredere onderwerp van mixed content buiten de mediabibliotheek behandel ik in mijn artikel over mixed content-waarschuwingen in WordPress.

Je weet dat de fix werkt zodra het grid weer met thumbnails wordt opgebouwd, de browser-console geen mixed-content-blokkades meer meldt voor afbeeldingsrequests, en een verse upload meteen in het grid verschijnt.

Oorzaak 6: de Big Image Threshold en de -scaled-val

WordPress 5.3 introduceerde de filter big_image_size_threshold, met als default 2560 pixels op de langste kant. Upload je een afbeelding groter dan die drempel, dan schaalt WordPress hem omlaag en slaat de geschaalde kopie op met een -scaled-suffix achter de bestandsnaam. Het -scaled-bestand wordt de nieuwe "full" size die wp_get_attachment_image_src('full') teruggeeft. Het ongewijzigde origineel blijft op schijf bewaard, en de bestandsnaam ervan wordt opgeslagen in de original_image-key van de _wp_attachment_metadata-array.

Even precies over wat er in 5.3 veranderde: de signature van wp_get_attachment_image_src() is niet veranderd. Wat veranderde is dat de URL die de functie voor "full" teruggeeft, nu naar de -scaled-kopie wijst zodra de upload de drempel overschreed. Nieuwe helpers wp_get_original_image_path() en wp_get_original_image_url() onthullen het origineel.

De val voor de mediabibliotheek is het migratiescenario. Stel: een site uploadt een 4000x3000-foto vóór WP 5.3 en upgradet daarna naar 5.3 of nieuwer. Database en schijf weerspiegelen allebei de pre-5.3-layout: één bestand, geen -scaled-kopie. Nieuwe uploads na de upgrade volgen de nieuwe layout. Komt er daarna een server-migratie die bestanden gedeeltelijk overzet, of een backup-tool die sommige bestanden wel terugzet en andere niet, dan kun je eindigen met database-entries die een -scaled-bestand verwachten dat niet bestaat, of die een origineel verwachten waarvan de migratietool alleen de geschaalde versie heeft meegenomen.

De diagnose begint in wp-admin. Kies een gebroken attachment en open de bewerkpagina. Het veld "Bestands-URL" toont het pad dat WordPress heeft opgeslagen. Open die URL in een nieuw tabblad. Krijg je een 404, kijk dan of de bestandsnaam -scaled bevat. Check vervolgens de werkelijke bestanden op schijf via de bestandsbeheerder van je hostingpaneel of SFTP: navigeer naar de bijbehorende map onder wp-content/uploads/ en kijk of het -scaled-bestand bestaat, het origineel bestaat, of allebei. Een mismatch tussen wat de database verwacht en wat er op schijf staat is de oorzaak. Heb je SSH-toegang? Dan toont wp post meta get <id> _wp_attachment_metadata de volledige metadata inclusief de entries file, original_image en sizes.

De fix is zelden "gooi het -scaled-bestand weg"; dat sloopt de full size voor nieuwe attachments. De juiste zet is sub-sizes regenereren (via de Regenerate Thumbnails-plugin uit oorzaak 4, of wp media regenerate --only-missing als je WP-CLI hebt) zodat de -scaled-kopie opnieuw wordt gebouwd vanuit het origineel dat wel aanwezig is, en checken dat de post meta met de schijf overeenkomt. Wil je echt de drempel uitzetten voor nieuwe uploads op een site die zijn eigen schaling regelt, geef dan nul terug uit de filter:

// wp-content/mu-plugins/disable-big-image-threshold.php
add_filter( 'big_image_size_threshold', '__return_zero' );

Hem in mu-plugins zetten betekent dat een theme- of plugin-update hem niet kan overschrijven. Maak het bestand aan via de bestandsbeheerder van je hostingpaneel of SFTP. Test dit eerst op staging; de drempel uitzetten betekent dat full-size originelen overal vanuit <img>-tags worden geserveerd, wat pagina's met veel afbeeldingen flink groter maakt.

Je weet dat de fix werkt zodra het grid thumbnails laat zien voor zowel oude als nieuwe attachments en een regeneratierun (via de Regenerate Thumbnails-plugin of wp media regenerate --only-missing) zonder fouten doorloopt.

Oorzaak 7: WebP, AVIF of HEIC geüpload naar een server die ze niet kan decoderen

Dit is een smallere variant van oorzaak 2 en het is de moeite waard om hem apart te noemen, want het symptoom lijkt sprekend op een rechtenprobleem. Je upload een .webp van een ontwerper of een .heic rechtstreeks vanaf een iPhone, de upload lijkt te slagen, het attachment bestaat in de bibliotheek, maar de thumbnail is een gebroken icoon en ook de detailweergave geeft geen preview.

De oorzaak is dat WordPress 5.8 native WebP toevoegde, 6.5 AVIF, en 6.7 automatische HEIC-naar-JPEG-conversie, maar elke toevoeging hangt af van de actieve image library op de server. De dev posts over WebP, AVIF en HEIC maken de afhankelijkheid expliciet. Is GD op PHP 8.0 je actieve editor, dan werkt AVIF überhaupt niet, want de GD AVIF-functies kwamen pas in PHP 8.1. Is Imagick je actieve editor maar is de ImageMagick van je host zonder HEIC gecompileerd, dan worden HEIC-uploads niet geconverteerd.

De diagnose is dezelfde als bij oorzaak 2: open Site Health onder Gereedschap: Sitediagnose: Info: Mediabeheer en check of het formaat dat je hebt geüpload in de lijst van ondersteunde formaten van de actieve editor staat. Staat het er niet bij, dan staat het bestand wel op schijf maar kon WordPress er geen sub-sizes voor genereren, en valt het grid terug op een placeholder.

De fix is server-side: zet de codec aan, wissel van image library, of converteer het bestand naar een formaat dat WordPress wel aankan (JPEG, PNG, WebP) voordat je upload. Op managed hosting vraag je de host om AVIF- of HEIC-ondersteuning te bevestigen en aan te zetten als dat nodig is. Je weet dat de fix gelukt is zodra Site Health het formaat onder de actieve editor noemt en een nieuwe upload sub-sizes oplevert die in het grid verschijnen.

Wanneer je hulp moet inschakelen

Heb je oorzaken 1 tot en met 7 doorlopen en toont de mediabibliotheek nog steeds lege tegels? Verzamel dan het volgende voordat je een ticket opent of een ontwikkelaar erbij haalt. Het eerste wat iemand met ervaring zal vragen, is precies dit lijstje:

• Je WordPress-versie, PHP-versie en de actieve image editor met ondersteunde formaten uit Sitediagnose: Info: Mediabeheer.
• Een specifiek attachment-ID dat stuk is, de waarde van de _wp_attached_file-post meta ervan, en het werkelijke bestandspad op schijf voor hetzelfde attachment.
• De HTTP-statuscode die je krijgt als je de gebroken thumbnail-URL rechtstreeks in een nieuw tabblad opent (200, 403, 404 of iets anders).
• De console-output van je browser op de mediabibliotheek-pagina, inclusief eventuele mixed-content-waarschuwingen.
• Of de site recent is gemigreerd, naar HTTPS is overgezet, een ander theme heeft gekregen, of dat wp-content/uploads handmatig over SFTP is aangeraakt.
• De output van wp media regenerate --only-missing --dry-run als je WP-CLI-toegang hebt, die per attachment laat zien welke sub-sizes ontbreken.
• De volledige _wp_attachment_metadata-waarde van één gebroken attachment (wp post meta get <id> _wp_attachment_metadata).

Stuur dat in de eerste boodschap mee. Het ticket gaat dan zonder extra rondje naar de juiste engineer.

Veroorzaakt dezelfde wortelproorzaak ook andere mediagerelateerde issues? Twee aanpalende artikelen behandelen specifieke vlakken van hetzelfde probleemterrein: het artikel over de HTTP-fout bij media-uploads gaat over uploads die mislukken voordat het bestand überhaupt in de bibliotheek belandt, en het artikel over mixed content-waarschuwingen behandelt de SSL-kant breder dan alleen de mediabibliotheek.

Hoe je het terugkomen voorkomt

De meeste van de zeven oorzaken delen één rode draad: ze duiken op na een wijziging die bestanden, paden of URL's heeft aangeraakt. Drie gewoontes voorkomen het leeuwendeel.

• Migreer wp-content/uploads en de database in één operatie. Tools als WP Migrate of de All-in-One WP Migration-plugin houden de post meta en de bestandspaden op de bestemming consistent. Handmatige SFTP plus een SQL-dump is waar de meeste oorzaak-3-incidenten vandaan komen.
• Switch in één operatie naar HTTPS, inclusief een search-replace. siteurl op HTTPS zetten is het makkelijke deel. Een database-brede search-replace voor http://yoursite.nl is het deel dat mensen overslaan, en het is precies het deel dat de grid-view-only mixed content-bug veroorzaakt.
• Check Site Health na elke PHP- of image library-upgrade. Een PHP minor version-bump kan een codec laten vallen die de vorige build wel had. Vertrouwt je site op AVIF of HEIC, dan is Gereedschap: Sitediagnose: Info: Mediabeheer het ene paneel dat het waard is om te checken na elke wijziging op host-niveau.