The portfolio page used to show a tidy grid of project photos that opened large when clicked. Now some thumbnails are grey squares, the grid has collapsed into one long column, or clicking a photo opens the raw image file on a blank white page instead of the nice lightbox.
WordPress gallery not working covers three different faults that people describe with the same words: images that do not load, a layout that has fallen apart, and a click that no longer opens the image the way it should. Each has its own short list of causes. Pick the one that matches what you see, and skip the others.
WordPress gallery not working? First find out what built it
Galleries on WordPress sites come from one of three sources, and the fix depends on which.
- The Gallery block in the WordPress block editor. Images are ordinary media library items, and the block saves standard markup in the page.
- A page builder gallery widget (Elementor, Divi, a theme’s own builder). The builder generates the layout and often adds its own lightbox.
- A dedicated gallery plugin such as NextGEN Gallery, Envira Gallery, FooGallery or Modula. These keep their own gallery settings, and some keep their images in their own folders rather than the normal uploads structure.
Click the gallery in the editor. The panel that opens tells you which you are dealing with. If the page shows a shortcode such as [ngg ...] or [envira-gallery ...], it is a plugin gallery.
Gallery images not loading
Grey boxes, broken-image icons, or empty spaces where thumbnails should be. Open the page in a browser, right-click a missing image, and choose “Open image in new tab” or Inspect it to see its address. That address is the best clue you have.
The address points at an old domain or an old folder
If the image address contains a different domain, a staging address, or http:// on an HTTPS site, the gallery is still referencing where the site used to live. The standard search-and-replace done during a move does not always reach every plugin’s own tables or serialised settings. Gallery plugins that store paths in their own way are frequent casualties. Our guide on problems that appear after a site move covers this family of faults.
The thumbnail size does not exist
WordPress creates several resized copies of each uploaded image. A gallery usually shows one of those copies, not the original. If the theme was changed, it may ask for thumbnail sizes that were never generated for older images, and the gallery requests a file that is not there. Image addresses ending in something like -300x300.jpg that return a “not found” error point to this. Regenerating thumbnails with a plugin built for the job creates the missing sizes. Our guide on images showing at the wrong size goes into how WordPress handles these copies.
The files are missing from the server
If the address looks right and the file simply is not there, the image never made it to this server. This happens when only the database was moved, or when a gallery plugin’s own folder was left out of a backup. Check whether the same image still appears in Media, then Library. If the media library shows a blank placeholder too, the file needs restoring from a backup or re-uploading.
Lazy loading waits for a trigger that never fires
Gallery plugins, speed plugins and WordPress itself can all apply lazy loading, which holds images back until they are about to scroll into view. If two of them overlap, or a speed plugin delays the script that does the loading, images further down a gallery may never appear. The test: scroll slowly to the gallery in a private window and wait. If images pop in late or not at all, check the speed plugin’s lazy-load and “delay JavaScript” settings and exclude the gallery.
The image format is not supported
Photos uploaded straight from some phones arrive as HEIC files, which many browsers cannot display. A gallery of HEIC images can look fine on the phone that took them and broken elsewhere. Convert them to JPEG or WebP before uploading, unless you have confirmed your site already converts them on upload.
The gallery layout is broken
All the images load, but the grid has gone wrong: one column instead of three, uneven gaps, images overlapping, or a masonry layout piled up at the top.
- The gallery’s CSS did not load. A speed plugin that combines or removes “unused” CSS can drop the gallery’s stylesheet, especially if the gallery sits on only one page. Exclude the gallery plugin’s CSS from that optimisation and clear the cache.
- A masonry or justified layout measured too early. These layouts work out positions from each image’s size. If they run before images have loaded, everything stacks at the top. The cause is usually lazy loading or delayed scripts again.
- The theme’s styles are overriding the gallery’s. After a theme update, a new rule for images inside content can change widths or margins for every image, including gallery ones.
- Column settings differ by screen size. Page builder galleries often have separate column counts for desktop, tablet and phone. A single column on mobile may be a setting, not a fault.
Clicking an image does not open the lightbox
A lightbox is the overlay that shows a large version of the image with arrows to move through the set. When it fails, clicking opens the image file on its own white page, or does nothing at all.
- Check the gallery’s link setting. The Gallery block and most gallery tools have a “Link to” option: none, media file, attachment page, or “expand on click”. If it is set to “none” or the attachment page, the lightbox has nothing to open. A lightbox plugin generally needs images linked to the media file.
- Count the lightboxes. A theme, a page builder and a gallery plugin can each include a lightbox. Two lightboxes trying to grab the same click can cancel each other out, or open two overlays. Turn off all but one in their settings.
- Look for a script error. Open the browser console on that page and reload. A red error in another script, or a missing jQuery, can stop the lightbox from starting. Our post on jQuery errors in the browser console covers the most common one.
Galleries that work but take an age to appear
Sometimes nothing is broken in the strict sense. The gallery loads, eventually, but visitors on a phone see empty boxes for several seconds and leave. That is usually a size problem rather than a fault. A gallery of forty photos uploaded straight from a camera can mean many megabytes of images, even when the thumbnails look small on screen, if the gallery is showing the full-size files scaled down by the browser.
Check one thumbnail’s address again. If it is the original file name with no size suffix, the gallery is loading full-size images as thumbnails. Most gallery tools have an image size setting; choose a medium or thumbnail size for the grid and keep the full size for the lightbox only. Compressing photos before upload and splitting very large galleries across pages, or adding a “load more” button, also helps. Our guide to optimising images for the web covers the compression side.
Notes worth making before you change settings
A broken gallery is usually the result of something else that changed, and the same change usually explains every broken gallery on the site. Before trying fixes, write down:
- Which tool built the gallery, and its version.
- Whether every gallery on the site is affected or only one.
- One missing image’s full address, copied from the browser.
- What changed recently: a move, a new theme, a speed plugin, an update.
A single gallery broken while the others work points to that gallery’s own settings. Every gallery broken at once points to the change that affected them all.
A slider is not a gallery, but it fails the same way
If the page has an image carousel rather than a grid, most of the lazy-loading and script-delay points above still apply. Our guide on a frozen or blank image slider covers the extra causes specific to sliders.
When it is time to hand over
Missing files that no backup contains, image paths buried in a gallery plugin’s own tables after a migration, and conflicts between two lightboxes built into a theme are all fixable, but they are easier to get wrong than they look, and a careless database replacement can break more than the gallery. If you are at that point, our wordpress bug fixes page explains how we take on jobs like this. Send the gallery page address and one broken image address, which is often enough to show which of the three faults it is.
Grey boxes, a collapsed grid or a lightbox that will not open each have their own short list. Start with the image address; it says more than any setting.
Next in this series: WordPress Google Map Not Showing? Read the Error First
