Redis caching can dramatically speed up WordPress sites by offloading expensive database queries and serving cached content quickly. The widely used Redis Object Cache plugin makes integrating Redis seamless. However, if the Redis server becomes unreachable, you are shown a rather unprofessional looking ‘Can’t connect to Redis’ error, instead of your website. The solution is to manually remove the object-cache.php drop in file, and the website will revert to loading without Redis.
This single point of failure is unacceptable for sites that require high availability. The ideal solution is graceful degradation: if Redis is down, WordPress should continue serving content from the database without caching, ensuring uninterrupted site access.
Check Redis is available before loading the plugin
We needed therefore, to check if Redis was available, before attempting to connect via the plugin. A common strategy for early execution in WordPress is to use a Must-Use (MU) plugin, placed in wp-content/mu-plugins
. MU plugins load early, but not early enough in this case.
object-cache.php
– the Redis plugin’s drop-in cache file is loaded before MU plugins. That means:
- If Redis is down,
object-cache.php
throws fatal errors before the MU plugin can intervene. - Therefore, a fallback strategy relying solely on MU plugins cannot prevent Redis-caused fatal errors.
Because of this, the only viable place to check Redis availability and conditionally disable the drop-in is before object-cache.php
loads. Not many things load before object-cache, but wp-config.php is one of them.
Our Solution: Early Redis Health Check in wp-config.php
We created a Redis fallback handler embedded directly into wp-config.php
. This script performs a rapid connectivity check to Redis before WordPress attempts to load the Redis object cache drop-in. I’ve included our code below in case it’s useful to anyone else. It was largely generated (and refined A LOT) using Gemini, which I’ve found is a great companion for the web developer. It’s actually now taken over from ChatGPT as my favourite coding buddy as the code it produces seems to be more comprehensive than ChatGPT. But I’ve got off topic. Back to the code.
Key Features:
- Checks Redis availability using the Predis client library.
- If Redis is unreachable, it renames
object-cache.php
to disable it temporarily. - If Redis comes back, it restores the drop-in automatically.
- Includes detailed logging (toggleable) for debugging and monitoring.
Code Snippet: wp-config.php
Integration
You insert the following code in your wp-config.php file. Just below the database settings is fine.
<?php
/**
* Define Redis settings and error handling.
*/
define( 'WP_REDIS_PREFIX', 'uniquekey_' );
define( 'WP_REDIS_DB', 1 );
// Redis server connection settings
define( 'REDIS_HOST', '127.0.0.1' );
define( 'REDIS_PORT', 6379 );
// Enable or disable detailed fallback debug logs
define( 'WP_REDIS_FALLBACK_DEBUG', true );
// Include the Redis health check script *before* wp-settings.php loads
require_once __DIR__ . '/wp-config-includes/redis-health-check.php';
Redis Fallback Handler: redis-health-check.php
You then need to create the folder wp-config-includes/
and put redis-health-check.php
in it.
<?php
// Prevent direct access
if ( ! defined( 'ABSPATH' ) ) {
die( 'Direct access not allowed.' );
}
// Enable debug logging
if ( ! defined( 'WP_REDIS_FALLBACK_DEBUG' ) ) {
define( 'WP_REDIS_FALLBACK_DEBUG', true );
}
function redis_fallback_wpconfig_log( $msg ) {
if ( WP_REDIS_FALLBACK_DEBUG ) {
error_log( '[WP-Config Redis Fallback] ' . $msg );
}
}
// Load Predis if needed
if ( ! class_exists( 'Predis\Client' ) ) {
$predis_autoloader = WP_CONTENT_DIR . '/plugins/redis-cache/dependencies/predis/predis/src/Autoloader.php';
if ( file_exists( $predis_autoloader ) && ! class_exists( 'Predis\Autoloader' ) ) {
require_once $predis_autoloader;
Predis\Autoloader::register();
redis_fallback_wpconfig_log( 'Predis autoloader loaded.' );
} else {
redis_fallback_wpconfig_log( 'Predis autoloader not found or already loaded.' );
}
}
$dropin_path = WP_CONTENT_DIR . '/object-cache.php';
$disabled_path = WP_CONTENT_DIR . '/object-cache-disabled.php';
// Fix: corrected IP typo here
function redis_is_available_for_wpconfig( $host = '127.0.0.1', $port = 6379, $timeout = 0.5 ) {
try {
$redis = new Predis\Client([
'scheme' => 'tcp',
'host' => $host,
'port' => $port,
'timeout' => $timeout,
'read_write_timeout' => $timeout,
]);
$redis->connect();
return (string) $redis->ping() === 'PONG';
} catch ( Exception $e ) {
redis_fallback_wpconfig_log( 'Redis connection failed: ' . $e->getMessage() );
return false;
}
}
$redis_host = defined( 'REDIS_HOST' ) ? REDIS_HOST : '127.0.0.1';
$redis_port = defined( 'REDIS_PORT' ) ? REDIS_PORT : 6379;
redis_fallback_wpconfig_log( "Checking Redis at $redis_host:$redis_port" );
$redis_available = redis_is_available_for_wpconfig( $redis_host, $redis_port );
redis_fallback_wpconfig_log( 'Redis available? ' . ( $redis_available ? 'Yes' : 'No' ) );
// Disable object-cache.php if Redis is down
if ( file_exists( $dropin_path ) && ! $redis_available ) {
if ( ! file_exists( $disabled_path ) ) {
if ( rename( $dropin_path, $disabled_path ) ) {
error_log( 'Redis down — disabled object-cache.php to prevent crash.' );
redis_fallback_wpconfig_log( 'object-cache.php renamed to object-cache-disabled.php' );
} else {
error_log( 'Failed to rename object-cache.php; check permissions.' );
}
}
}
// Restore object-cache.php if Redis is back
if ( file_exists( $disabled_path ) && $redis_available ) {
if ( rename( $disabled_path, $dropin_path ) ) {
error_log( 'Redis restored — object-cache.php re-enabled.' );
redis_fallback_wpconfig_log( 'object-cache-disabled.php renamed to object-cache.php' );
} else {
error_log( 'Failed to restore object-cache.php; check permissions.' );
}
}
Benefits and Impact
- Prevents fatal errors caused by Redis unavailability.
- Ensures your WordPress site remains online, even during Redis outages.
- Automatically self-heals, restoring caching once Redis is back.
- Provides detailed logging to help monitor Redis health and troubleshoot.
Final Thoughts
If you’re relying on Redis caching in WordPress, don’t overlook what happens when Redis goes down. There are plenty of config options available within the redis.conf file, however even then, you need to consider the impact on your site if Redis does just go away for some reason. Our solution was to embed a lightweight Redis health check directly into wp-config.php
. We found it was the safest and most reliable way to continue using Redis on the website when Redis is available, but automatically remove Redis as a dependency if it’s unexpectedly not available.