WordPress Errors

WordPress Header Image Not Showing

Warning Updated: June 4, 2026

What Is This Error?

You’ve uploaded a header image in WordPress, hit save, and refreshed your site — but the header area is blank or still showing the old image. This is a frustratingly common visual bug that catches a lot of WordPress users off guard, especially after switching themes or doing a fresh install.

The good news is that the image itself is usually fine. The problem almost always traces back to caching, a theme configuration mismatch, or an image that was added to the wrong place during upload. In most cases, you won’t need to touch any code at all.

This guide walks you through every likely fix in priority order, from the simplest to the more technical — start at the top and work your way down.

Why Does This Happen?

  • Caching is serving a stale page — Your browser, a caching plugin like WP Rocket or W3 Total Cache, or a CDN may be holding onto a version of your page that predates the header image upload.
  • The image was uploaded to the wrong place — Dropping an image into the Media Library doesn’t assign it as your header. It must be set explicitly through Appearance → Customize → Header Image.
  • Image dimensions don’t match the theme’s requirements — Most themes expect a specific header image width and height. If your image is too small or has a wildly different aspect ratio, the theme may skip rendering it entirely.
  • A CSS rule is hiding the image — A plugin, custom CSS block, or child theme stylesheet might contain a rule like display: none or visibility: hidden targeting the header element or its image tag.
  • The active theme doesn’t support custom headers — Some older or heavily customized themes never registered the custom-header feature, so WordPress has no built-in slot to output the image.

How to Fix It — Step by Step

  1. Clear every cache layer first — Open your browser’s history settings and clear cached images and files (Ctrl+Shift+Delete on Windows, Cmd+Shift+Delete on Mac). Then go to your caching plugin’s dashboard and purge all caches. If you’re using Cloudflare or another CDN, purge that too.

    You should see: The site reloads fully from the server, with no cached output served.

  2. Re-assign the header image through the Customizer — Navigate to Appearance → Customize → Header Image. Click “Add new image,” select or upload your photo, and click Publish. This is the only reliable way to register a header image in WordPress — don’t rely on the Media Library alone.

    You should see: A live preview of the header image appears in the Customizer panel on the right side.

  3. Verify and match the recommended image dimensions — Inside the Customizer header section, WordPress usually displays a note like “Suggested: 1280 × 250 pixels.” Resize your image to match those dimensions using a tool like Canva or GIMP, compress it under 500 KB, and re-upload.

    You should see: The image fits cleanly in the header area without blank space or unexpected cropping.

  4. Inspect the header element for CSS conflicts — Right-click the header area in your browser and select “Inspect.” In the Styles panel, look for any rule applying the following to the header or its child image tag: 
    /* Rules that would hide your header image */
header { display: none; }
.site-header img { visibility: hidden; }
.custom-header { opacity: 0; }

    You should see: No conflicting CSS rules are crossed out or overriding the header image’s visibility.

  5. Deactivate plugins one by one — Page builders, CSS optimization plugins, and security plugins can all interfere with header rendering. Go to Plugins → Installed Plugins and deactivate them individually, refreshing the front end after each one to isolate the culprit.

    You should see: The header image reappears as soon as the conflicting plugin is deactivated.

  6. Add custom-header support to your child theme — Open your child theme’s functions.php and check whether add_theme_support( 'custom-header' ) exists. If it’s missing, add the following block: 
    add_theme_support( 'custom-header', array(
    'default-image' => '',
    'width'         => 1280,
    'height'        => 250,
    'flex-width'    => true,
    'flex-height'   => true,
) );

    You should see: The Header Image option appears inside Appearance → Customize after saving the file.

Common Mistakes When Fixing This

  • Uploading to the Media Library and expecting it to appear — The Media Library is storage, not configuration. Placing an image there has zero effect on your header. You must assign it through the Customizer.
  • Checking the site before clearing caches — Lots of people re-upload the image, glance at the frontend, see nothing changed, and give up. Always purge all caches before judging whether a fix worked.
  • Editing the parent theme’s functions.php directly — Any change you make to a parent theme file gets overwritten on the next theme update. Always apply code modifications inside a child theme to keep them safe.
  • Uploading an oversized or uncompressed image — A raw 8 MB photo can time out mid-upload or get partially written to disk, resulting in a broken image reference. Compress header images to under 500 KB before uploading.

Frequently Asked Questions

The header image shows in the Customizer preview but not on the live site — why?

This is almost always a caching issue. The Customizer preview bypasses most caches to give you a real-time render, but your live site serves cached output. Purge your caching plugin, CDN, and browser cache, then reload the live URL.

Does the image file format matter — JPG vs PNG vs WebP?

Most WordPress themes handle JPG and PNG without any issues. WebP is natively supported from WordPress 5.8 onward, but some older themes may not render it correctly in the header slot. When in doubt, use a compressed JPG — it’s the most universally compatible option.

Will switching to a different theme fix this?

It depends on the root cause. If your current theme simply doesn’t support custom headers, switching to one that does (like Twenty Twenty-Three) will resolve it immediately. But if the issue is caching or a wrong upload method, the problem will follow you to whichever theme you switch to.

My header image disappeared after a WordPress update — is that normal?

It can happen. A core or theme update occasionally resets Customizer settings if there’s a compatibility mismatch. Go back to Appearance → Customize → Header Image and re-assign the image. Also make sure your theme is updated to its latest version to restore full compatibility.

Related Error Fixes