WordPress Header Image Not Showing: How to Find and Fix the Cause

This article is a localized edition of the Japanese original. Read the Japanese original

When your WordPress header image is not showing, the fastest fix is to narrow down where the problem is, one layer at a time. Check in this order:

1. Whether your theme supports the header image feature (custom-header)
2. Whether a header image setting is saved for the current theme
3. Whether the template actually outputs the image
4. Whether the image URL loads and the image is not hidden by CSS
5. Whether an old page is still being served from a cache

Everything in this article was checked against the WordPress 6.9 source code (as of October 2026).

Narrow it down by symptom

1. Check whether the theme supports custom-header

The header image settings only appear when the theme declares the feature with add_theme_support( 'custom-header' ). If it does, you can set the image under "Appearance" → "Header" (外観 → ヘッダー in the Japanese UI), or under "Appearance" → "Customize" → "Header Image" ("Header Media" in themes that also support video).

If you can use WP-CLI, this command tells you whether the feature is supported:

wp eval 'var_dump( current_theme_supports( "custom-header" ) );'

If it prints bool(false), the theme has no header image feature. You have two options:

• Block themes (such as the default themes from Twenty Twenty-Two onward): you edit the header in the Site Editor. Go to "Appearance" → "Editor", open the header template part, and add an Image block or a Cover block. The Customizer header image is not used.
• Classic themes without the feature: check whether the theme has its own settings screen with a header image option. If you are building your own theme or child theme, declare the feature in functions.php.

<?php
// functions.php (classic theme)
add_action( 'after_setup_theme', function () {
	add_theme_support(
		'custom-header',
		array(
			'width'       => 1920,
			'height'      => 400,
			'flex-width'  => true,
			'flex-height' => true,
			'header-text' => false,
		)
	);
} );

width and height are the recommended size and are used as the crop target when you pick an image in the Customizer. Setting flex-width and flex-height to true lets that dimension accept images that differ from the recommended size. Declaring support alone does not display the image; you also need the template output described in step 3.

2. Check the saved header image setting

If you are sure you chose an image but it does not show up, look at the stored value:

wp theme mod get header_image

The header image setting is stored per theme, in an option named theme_mods_{theme-folder-name}. That means the image you chose is not carried over right after you switch from a parent theme to its child theme, or to any other theme. Open the Customizer with the current theme, choose the image again and click "Publish".

3. Check that the template outputs the image

In a classic theme, a template such as header.php needs code that displays the header image. Check that your theme (and, with a child theme, any header.php you copied into the child theme) contains output like the following.

To output an image tag, the_header_image_tag() is the easiest option. It prints an img tag with width, height, alt and, when available, srcset.

<?php if ( has_header_image() ) : ?>
	<div class="site-header-image">
		<?php the_header_image_tag(); ?>
	</div>
<?php endif; ?>

If you only need the URL, mind the difference between these functions:

To print the URL directly in a template, use header_image():

<?php if ( has_header_image() ) : ?>
	<div class="site-hero" style="background-image: url('<?php header_image(); ?>');"></div>
<?php endif; ?>

When you store the URL in a PHP variable, use get_header_image() and pass it through esc_url() when you print it. If you write esc_url( header_image() ), header_image() prints the URL on the spot and esc_url() receives nothing, so the URL does not end up where you intended.

<?php
// functions.php: write the image into CSS as a background image
add_action( 'wp_head', function () {
	if ( ! has_header_image() ) {
		return;
	}
	printf(
		'<style>.site-hero{background-image:url("%s");}</style>' . "\n",
		esc_url( get_header_image() )
	);
} );

When you show the image as a background, it is invisible if the element has no height. Give .site-hero a min-height or similar.

4. Check the image URL and CSS

Open the URL you got in step 2 directly in your browser.

• It returns 404: the image may have been deleted from the Media Library, or the site was moved and the URL still points to the old domain. Choosing the image again is the simplest fix. If many URLs still point to the old address after a move, use wp search-replace, which also replaces serialized values correctly. Check the counts first with --dry-run, then run it, and back up the database before you start.

wp search-replace 'http://old.example.com' 'https://www.example.com' --dry-run

• The image opens but does not appear on the page: select the header element in your browser's developer tools. Check whether it has display: none or a height of 0, and whether the console shows a mixed content warning (an http image loaded on an https page).

5. Clear caches and check again

If you still see the old image after changing the setting, a cache is involved. Clear them in this order:

1. Browser: reopen the page in a private window to rule out the browser cache
2. Page cache plugin: use the cache-clearing feature in the plugin's settings screen or the admin bar
3. Server or CDN cache: if your host has a cache feature or you use a CDN, clear it from that control panel
4. Object cache: if you use Redis or Memcached, you can clear it with WP-CLI

wp cache flush

wp cache flush empties the object cache; it does not delete HTML cached by a page cache plugin. There is no option such as --hard, so clear the page cache with the plugin's own feature.

Changing header image settings from a child theme

If you want a child theme to change values the parent theme set, such as the recommended size, watch how add_theme_support( 'custom-header' ) behaves. When the feature is declared twice, WordPress keeps the values registered first. In addition, width, height, header-text, default-image and default-text-color are locked into constants (such as HEADER_IMAGE_HEIGHT) the first time they are registered. So declaring the feature again after the parent theme (for example at priority 11 on after_setup_theme), or removing it with remove_theme_support() and registering it again, does not change the parent theme's height or width.

To make the child theme's values win, register them before the parent theme does. Any keys the child theme does not set are filled in from the parent theme's later registration.

<?php
// Child theme functions.php
add_action( 'after_setup_theme', function () {
	add_theme_support(
		'custom-header',
		array(
			'default-image' => get_stylesheet_directory_uri() . '/images/header-default.jpg',
			'height'        => 600,
			'flex-height'   => true,
		)
	);
}, 9 ); // Runs before the parent theme (when the parent registers at priority 10)

In this example the height is the child theme's 600, and keys you did not set, such as the width, come from the parent theme. To find where the parent theme registers the feature, search the parent theme's files for add_theme_support( 'custom-header'.

• If it registers on after_setup_theme without a priority (priority 10), priority 9 as in the example above runs first
• If it uses priority 9 or lower, give the child theme a smaller number
• If it calls the function directly in functions.php without a hook, call add_theme_support() directly in the child theme's functions.php as well. The child theme's functions.php is loaded before the parent theme's functions.php

The image set in default-image is shown for a theme where no header image has ever been chosen. It is not shown when the value from step 2 is remove-header.

Summary

• First check theme support with current_theme_supports( 'custom-header' ). Block themes edit the header in the Site Editor
• Read the stored value with wp theme mod get header_image. The setting is per theme, so choose the image again after switching to a child theme
• In templates, output the image with the_header_image_tag() or header_image(). When you need a variable, use get_header_image() with esc_url()
• Open the image URL directly and check for 404 errors, CSS and mixed content
• wp cache flush only clears the object cache. Clear page caches with your plugin's or CDN's own feature

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)