Full Page Cache for WordPress 404s

v1.0.3 2024-03-22 20:53 UTC


Coding Standards Testing Suite

A WordPress plugin to provide full page caching for 404 pages, improving performance and reducing server load.

  • Contributors: alleyinteractive
  • Tags: alleyinteractive, wp-404-caching
  • Stable tag: 1.0.3


  • SSL enabled on the website.
  • An external object cache setup (e.g., Redis, Memcached).
  • Requires at least: 6.3
  • Tested up to: 6.4
  • Requires PHP: 8.1
  • License: GPL v2 or later


WP 404 Caching is a lightweight plugin that efficiently serves cached 404 pages to non-logged-in users. It reduces server load by storing the cached 404 page in an external object cache and returning it early in the request process.

The plugin uses a dual regular/stale caching strategy to minimize cache misses. It maintains a regular cache with a 1-hour expiration and a stale cache with a 1-day expiration. If the regular cache is empty, the stale cache is served.


  • Full page caching for 404 pages
  • Utilizes external object cache for storing cached 404 pages
  • Dual regular/stale caching strategy to minimize cache misses
  • Automatically generates and caches 404 page via a "guaranteed 404 URI"
  • Triggers cache generation hourly via a cron job and immediately on cache misses
  • Sends X-WP-404-Cache header to indicate cache HIT/MISS status
  • Ensures compatibility with analytics by replacing the "guaranteed 404 URI" with the actual requested URI in the cached page


Via Composer (recommeded):

You can install the package via composer:

composer require alleyinteractive/wp-404-caching

Manual install:

  1. Upload the wp-404-caching directory to your /wp-content/plugins/ directory.
  2. Activate the plugin through the 'Plugins' menu in WordPress.


The plugin works out of the box with default settings. You can customize the cache expiration times by modifying the CACHE_TIME and STALE_CACHE_TIME constants in the Full_Page_Cache_404 class. Activate the plugin in WordPress and use it like so:

add_filter( 'wp_404_caching_cache_time', function( $cache_time ) {
    return 2 * HOUR_IN_SECONDS; // Set cache time to 2 hours.
} );

add_filter( 'wp_404_caching_stale_cache_time', function( $stale_cache_time ) {
    return 2 * DAY_IN_SECONDS; // Set stale cache time to 2 days.
} );

// Programmatically bypass the cache.
add_filter( 'wp_404_caching_enabled', '__return_false' );


Please see CHANGELOG for more information on what has changed recently.


This project is actively maintained by Alley Interactive. Like what you see? Come work with us.


The GNU General Public License (GPL) license. Please see License File for more information.

Developer Notes


Run composer test to run tests against PHPUnit and the PHP code in the plugin.