2026年11月13日

WordPress get_template_part Not Loading: Causes and Fixes

Errors & White Screen

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

When WordPress's get_template_part() fails, the cause is almost always one of two things: either "the file is not at the specified path (as far as WordPress can tell)," or "the file is loaded, but a variable or error problem occurs inside it." Because get_template_part() shows nothing and raises no error when it cannot find the file, the cause is hard to see. This article explains how the function searches for files, then covers common failure patterns and how to narrow down the cause by logging which files were searched for.

How get_template_part searches for files

First, let's pin down the function's specification precisely.

get_template_part( string $slug, string $name = null, array $args = array() );

For example, if you write get_template_part( 'template-parts/content', 'page' ), WordPress searches for files in this order.

template-parts/content-page.php
template-parts/content.php

Only the first file found is loaded. The places it searches are determined by locate_template(), which is used internally, and the order is child theme folder, then parent theme folder. If you are not using a child theme, only the active theme's folder is searched.

There are three key points.

$slug and $name are paths relative to the theme folder, without the .php extension.
$name is a variation that takes priority if it exists, and if it is not found, WordPress falls back to the file named by $slug alone.
In WordPress 5.5 and later, the function returns false when the file is not found. When the file is found, it returns nothing.

Common failure patterns

Adding the .php extension

// Wrong: it looks for content.php.php
get_template_part( 'template-parts/content.php' );

// Correct
get_template_part( 'template-parts/content' );

WordPress adds .php automatically, so if you write the extension, it ends up looking for content.php.php. This is one of the most common mistakes.

Passing a full path (the complete path on the server)

If you pass a full path such as get_template_directory() . '/template-parts/content', WordPress looks for a path in which the full path is appended after the theme folder, and it is not found. Pass get_template_part() only a path relative to the theme. To load a file outside the theme, use something like require instead of get_template_part().

Differences in case or folder names

In a local environment (the default settings of Windows or macOS), file names are often case-insensitive, so calling Content.php as content still works. But many production servers (Linux) are case-sensitive, so the file stops loading as soon as you upload it. When "it works locally but does not appear in production," suspect this first. A one-character difference in a folder name is also common, such as template-parts versus template-part, or parts versus part.

You think you put it in the child theme, but WordPress is looking at the parent theme (or the reverse)

When you want to override a file in a child theme, you need to put the file in the child theme at the same relative path as in the parent theme. If the parent theme loads template-parts/content.php, a content.php placed directly in the child theme is not used.

Conversely, if an old copy remains in the child theme, the child theme's file takes priority even after you update the parent theme, and your changes do not appear. If the display looks wrong after a parent theme update, check whether a file with the same name remains in the child theme.

Trying to call an HTML template part of a block theme

In block themes such as Twenty Twenty-Four, the header and footer template parts are HTML files such as parts/header.html. get_template_part() searches only for PHP files, so it cannot load them. To output an HTML template part from PHP, use block_template_part(), added in WordPress 5.9.

// Output parts/header.html
block_template_part( 'header' );

Calling it from inside a plugin

get_template_part() searches only the theme folder. A file in the plugin's folder will not be found even if you specify it. If you want a plugin to "use the file of the same name in the theme if there is one, and otherwise use the file inside the plugin," search with locate_template() first, and if nothing is found, load the file inside the plugin.

$template = locate_template( 'myplugin/card.php' );
if ( '' === $template ) {
	$template = plugin_dir_path( __FILE__ ) . 'templates/card.php';
}
load_template( $template, false );

When the file is loaded but the output looks wrong

Even when the file location is correct, it can "look like it failed" for the following reasons.

Variables from the caller are not available

A file loaded with get_template_part() runs inside a function, so local variables defined in the caller are not visible.

// Caller
$label = 'Recommended';
get_template_part( 'template-parts/card' ); // $label is undefined inside card.php

In WordPress 5.5 and later, you can pass values with the third argument $args. Inside the loaded file, you receive them as an array named $args.

// Caller
get_template_part( 'template-parts/card', null, array( 'label' => 'Recommended' ) );

<?php
// template-parts/card.php
$label = isset( $args['label'] ) ? $args['label'] : '';
?>
<span class="card-label"><?php echo esc_html( $label ); ?></span>

Escape output with something like esc_html(). The values in $args may come from input by authors or users, so escaping on the template side is the basic rule.

Note that template tags used in the loop, such as the_title() and get_the_ID(), refer to the global $post, so you can use them without passing them through $args.

A PHP error occurs inside the template part

If a fatal error occurs inside the loaded file, the output after that point may not appear, or the screen may go completely white. Enable the debug log in wp-config.php and check the error.

// wp-config.php (write this above the "That's all, stop editing!" line)
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Errors are recorded in wp-content/debug.log. If you investigate in a production environment, do not display errors on the screen (set WP_DEBUG_DISPLAY to false), and when you finish checking, set WP_DEBUG back to its original value.

A cache is serving an old display

If the display does not change even after you fix the file, a page-cache plugin, a server cache or PHP's OPcache may be returning old results. Clear the caches and then check again.

Narrow it down by logging which files were searched for

When you do not know the cause, recording which file names WordPress actually searched for lets you narrow it down quickly. Before searching for files, get_template_part() runs the get_template_part action and passes it the candidate file names it will search for (WordPress 5.2 and later). Use this to log only the ones that were not found.

// Child theme's functions.php (remove this when you finish investigating)
add_action( 'get_template_part', function ( $slug, $name, $templates, $args ) {
	if ( defined( 'WP_DEBUG' ) && WP_DEBUG && '' === locate_template( $templates ) ) {
		error_log( '[template part not found] ' . implode( ', ', $templates ) );
	}
}, 10, 4 );

When you display a page in this state, the template parts that were not found are recorded in debug.log in a form such as template-parts/content.php.php. If you compare the recorded file names with the actual file locations and names, a duplicated extension or a difference in case becomes obvious right away.

If you want to check at the call site individually, you can also use the return value.

if ( false === get_template_part( 'template-parts/content', get_post_type() ) ) {
	error_log( 'content template part not found for post type: ' . get_post_type() );
}

If nothing appears in the log but the part still does not display, the file was found and loaded, so continue your investigation in the direction of the variables, PHP errors or caches described above.

Summary

get_template_part( $slug, $name ) searches in the order {$slug}-{$name}.php then {$slug}.php, and child theme then parent theme, and it raises no error when nothing is found.
Most failures come from adding the .php extension, specifying a full path, differences in case, or putting the file in the wrong place in the child theme.
Handle HTML parts of block themes with block_template_part(), and files inside plugins with locate_template() and load_template().
Pass variables with the third argument $args (WordPress 5.5 and later) and escape them on the template side.
Logging with the get_template_part action lets you identify which file was searched for and failed (this is based on the WordPress specification as of October 2026).

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