WordPress: fix “Error establishing a Redis connection”

Distinguish Redis failure from WordPress’s main database

The site or administration login displays “Error establishing a Redis connection.” Redis acts here as persistent object cache, retaining reusable results across requests. This failure does not mean posts disappeared from MySQL or MariaDB. Do not replace main-database credentials to fix an error naming Redis.

The goal has two stages: restore controlled operation without this cache if necessary, then repair its connection and reactivate it. Temporary bypass does not repair Redis. It may increase database work, so monitor the site during this period.

This route targets self-hosted installations whose cache is managed by Redis Object Cache or an identified provider. On WordPress.com or managed hosting, files and service may be platform-controlled. In multisite, cache and configuration may concern several subsites: prepare intervention at that scope.

Prepare file access and preserve the precise error

Record the exact message, time, domain and last known change: migration, secret rotation, Redis maintenance or component update. Keep details privately. A diagnostic screenshot may reveal an internal server name or parameters; review it before publication.

Prepare SFTP or file-manager access working independently of WordPress. Privately back up the configuration file and cache drop-in before changes. A recent data backup remains necessary for broader work, but this procedure initially requires neither SQL restoration nor content deletion.

When the site is already unavailable, targeted bypass may restore service. Record its time and operations during that period. Old Redis keys may remain while WordPress data changes without invalidating them: reactivation must address this inconsistency. For configuration or version comparisons, use a copy with external effects disabled and cache isolated from production.

Identify the file actually providing object cache

WordPress may load a special object-cache.php file in its content directory. This drop-in differs from an ordinary plugin folder. The directory is often wp-content, but configuration may relocate it. Verify the actual site path and WP_CONTENT_DIR if customized.

Open a file copy read-only and inspect its header: component name, publisher and address. The Redis Object Cache drop-in declares its identity. If it belongs to another tool or provider, use their procedure, because this plugin’s constant does not apply to every Redis cache.

Do not rename the entire plugins directory for this failure. A drop-in may still load even if its plugin folder becomes inaccessible. Conversely, normal plugin deactivation may trigger cleanup. Identify owner and mechanism before choosing an action. The name object-cache.php alone identifies neither who installed it nor what data the service shares.

Choose a bypass that does not flush a shared database

If administration remains open, Settings, Redis shows cache state. Do not automatically choose Flush Cache or Disable Object Cache to diagnose a connection. In Redis Object Cache 3.0.0, interface deactivation removes the drop-in and then attempts to flush the Redis database used. In a cluster, this may target primary nodes. Different per-site key prefixes do not protect other data from this database flush.

If the provider confirms the entire targeted scope is dedicated to this cache and approves flushing, Disable Object Cache is its interface route. First preserve the file and initial state, apply once and verify site access. Successful drop-in removal does not prove remote flushing succeeded if Redis was inaccessible. Reactivation through Enable Object Cache therefore remains subject to consistency checks below. A completed flush cannot be undone with this button.

When sharing or impact is unestablished, prefer the constant-based bypass supported by the identified drop-in. It returns to operation without persistent cache without requesting a database flush. Without file permissions, have the administrator perform that precise action instead of trying several cleanup buttons.

Use the identified drop-in’s emergency constant

1. This method applies to the confirmed Redis Object Cache drop-in supporting WP_REDIS_DISABLED. Through file access, open the actual wp-config.php and retain a private copy. Search for an existing definition. If present, change its value; do not add a conflicting second definition.
2. If absent, place the line below in custom settings before loading wp-settings.php, without changing the PHP opening or other constants. Use boolean true without quotes. Save, then make a new administration request and open a page not served solely from old page cache.
3. The expected result is restored access with Redis bypassed. For a syntax error, immediately restore the preserved file. If the Redis error is unchanged, verify the loaded file and drop-in owner instead of multiplying constants. After service repair, restore the original value or remove only the added line according to reactivation below.

define( 'WP_REDIS_DISABLED', true );

Temporarily remove only the drop-in when necessary

1. This variant requires file access and confirmation that the owner authorizes removing its drop-in. Use it when the constant is unsupported or the provider requires this mechanism. First preserve a private copy of object-cache.php, its path, identity and permissions. Do not remove another cache’s file solely because of its name.
2. Through SFTP or file manager, move only this file to a prepared private location outside the public directory. The exact load path should no longer contain object-cache.php, without deleting the original. Move neither advanced-cache.php, the whole content directory nor main-database configuration.
3. Make a new request and check site recovery. If the file automatically returns, a management tool regenerates it: stop repeated removal and involve its owner. To restore initial state, return the confirmed copy to its exact path only after Redis repair. That potentially reactivates the blocking dependency; prepare the same emergency access.

Read diagnostics from the existing plugin

Redis Object Cache is published by Till Krüss. The documented version recorded is 3.0.0; it states minimum WordPress 4.6 and PHP 7.2, tested through WordPress 7.1.4. This describes declared component status, not a test of your installation. Installing the plugin alone does not create an available Redis server. These old technical minimums do not recommend retaining unmaintained PHP.

After access returns, open Settings, Redis, inspect state and then Diagnostics. In multisite, use My Sites, Network Admin, Settings, Redis with required network permissions. Record drop-in version, client and useful connection details. A constant-disabled state is expected during bypass. Do not confuse this intentional state with new evidence of service failure.

Keep complete diagnostics private and share only necessary details after hiding secrets. If the plugin reports an invalid drop-in or one owned by another tool, do not force replacement. Identify ownership first. A plugin/file version difference may call for a controlled update on a copy, but does not justify replacing a hosting-managed file.

Check the actually expected address, port and transport

Compare site configuration with private provider information: Redis host, port, TCP or TLS transport and possibly Unix socket path. Host here means the Redis service, not necessarily the WordPress database server. Migration may retain an address unreachable from the new PHP engine.

In wp-config.php or managed configuration source, find existing cache parameters. For Redis Object Cache these may include WP_REDIS_HOST, WP_REDIS_PORT, WP_REDIS_SCHEME or WP_REDIS_PATH. Do not add a second set if the provider already injects values elsewhere. Compare each with the current connection specification before changing anything.

127.0.0.1 means the connecting process’s local environment; in a container it is not automatically a neighboring Redis service. A port does not universally determine TLS use. With TLS, also check server name and certificate trust. Do not disable verification to turn a transport error into an apparently successful connection.

Distinguish authentication from command permissions

NOAUTH means authentication is required. A password or username error calls for comparison with the current Redis secret and account without touching the MySQL password. Verify through the provider’s private channel. Do not put the secret in a screenshot, diagnostic URL or public ticket. Redis Object Cache accepts WP_REDIS_PASSWORD as a string or user/password array for an ACL: confirm the expected form without copying an example secret into configuration.

NOPERM may appear after authenticated connection: the account lacks permission for a command or requested keys. Redis ACL rules can restrict both scopes. Correlate the rejected command, expected user and documented cache-client needs.

Do not respond by granting every permission to every account. Correction must target the needed account and scope, with the administrator retaining the initial rule. After modification, disappearance of NOAUTH is insufficient: necessary cache reads and writes must still work. An account may answer a connection test while real WordPress use remains denied.

Test reachability without writing or flushing cache

If the administrator already has redis-cli, they can run PING from the same network environment as PHP. Testing from a personal computer does not validate the site’s route. The example below targets TCP with ACL authentication; replace fictional host, port and user with confirmed values. Password entry is hidden through --askpass.

If the service uses TLS, add --tls and provider-required trust parameters. If it uses a socket, use that corresponding route instead of this TCP example. Do not put a password in visible arguments. This command creates no key and flushes no database.

PONG indicates this connection received a response. It validates neither every cache permission, PHP-client configuration nor the destination WordPress uses. Keep the result with test origin and time. Resolution, connection refusal, certificate and authentication errors point to different corrections.

redis-cli -h redis.exemple.invalid -p 6379 --user utilisateur-cache --askpass PING

Handle MISCONF and READONLY at service level

A MISCONF message saying an RDB snapshot cannot be saved to disk calls for the Redis administrator to examine persistence. The service may reject writes after this failure. Have logs, available space, permissions and resources for the failed operation checked.

Do not automatically disable persistence or its write-stopping mechanism to restore one site. The service may host other data whose retention matters. Temporarily keeping WordPress without this cache avoids turning site-access trouble into a global Redis policy change. The service administrator chooses the fix and checks expected operations resume.

READONLY may indicate connection to a replica rejecting writes. Have the expected endpoint and any role failover checked. Correction means restoring the intended cache service or routing, not arbitrarily making a replica writable. Increasing connection timeout or deleting keys fixes neither an incorrect replication role nor persistence failure.

Correct connection and prepare consistent cache

Once the cause is identified, change only the confirmed parameter in its effective source. Retain the old definition and avoid conflicting blocks. For injected secrets, use the provider’s mechanism. On a copy with isolated cache, verify actual transport and client type. For a PHP error, restore the preserved file and maintain bypass.

Before removing bypass, address keys present before the failure. While WordPress used internal cache, changes may have been saved without updating Redis. Those old values do not automatically become correct when service returns; some keys may never expire. Have deletion limited to this installation’s key space, or the entire affected multisite network, confirmed before rereading it.

If targeted invalidation is unavailable, the maintainer can prepare a fresh prefix with WP_REDIS_PREFIX, supported by this drop-in. It must be unique, stable and shared by instances serving the same installation, or the entire multisite network. Record the current prefix, verify ACL permissions for the new one, then change its single configuration definition before reconnecting. Keep bypass active on all those instances during the switch. Do not use a different random value on every request.

This change does not delete old keys: schedule their removal separately with the administrator, particularly to avoid persistent memory use. Do not reactivate the old prefix without checking consistency. If preparation fails, keep Redis bypassed. Unsupported options WP_REDIS_GRACEFUL or WP_REDIS_SELECTIVE_FLUSH are not guaranteed shortcuts. Full-database flushing remains restricted to a dedicated, expressly confirmed scope; no connection change requires restoring the entire WordPress database.

Reactivate caching and verify new requests

Once the administrator confirms connection and cache-space consistency, prepare return while keeping file access open. If you added WP_REDIS_DISABLED, remove only that line or restore its initial value. If you moved the drop-in, return the correct copy to its intended path. If disabled through the interface, use Enable Object Cache after the same checks. Disappearance of the connection error alone does not authorize reusing old keys.

Then make a new administration request and inspect Redis status. Verify bypass is no longer indicated and the intended connection is active. Compare a public page and administration screen, then a reversible change on the copy followed by rereading its value. An already page-cached page does not prove PHP reaches Redis. In multisite, also check a second subsite and relevant global data with the network administrator.

Monitor logs and database load during recovery. An empty cache must populate through use; no universal performance gain follows from reactivation alone. If blocking returns, reapply the known bypass and retain the new event. Do not loop through purge or reactivation buttons without examining the recurring cause.

Prepare future maintenance without hidden dependencies

Document the drop-in owner, actual content path, parameter source and Redis service used. Specify whether the database is dedicated or shared and who may authorize flushing. Retain the emergency procedure and its removal method; a forgotten constant may leave the site running long without cache the team believes active.

Before migration, verify access to the new service from PHP, authentication, transport and copy behavior. Before secret rotation or Redis maintenance, plan when each consumer will receive new configuration. PONG and public-page access do not replace functional object-cache validation.

For a correction request, provide plugin and drop-in versions, useful error code, time, environment and applied bypass. Keep secrets in their designated channel. The record should distinguish a wrong destination, denied authorization and degraded service. Repair is complete when cache works again and the site remains usable with consistent checks, without habitual blanket cleanup.

Turn the Redis message into a precise correction request

Use this decision guide with the private record without executing cleanup commands.

For each case, request two separate confirmations: “Does the site reach the correct service?” and “Can the PHP client perform expected cache operations?” PONG answers only part of the first. After correction, record plugin state again and verify a changed value reread on the copy. If diagnosis stays inconsistent, restore the documented bypass instead of flushing the whole Redis database. No paid external tool is needed for this classification.

1. NOAUTH: connection requires authentication. Compare configured identity and active secret; do not reset the MySQL account.
2. NOPERM: connection may be authenticated, but a command or key family remains denied. Provide command name and expected prefix with private values hidden. Correction concerns this consumer’s ACL.
3. MISCONF related to an RDB save: the administrator examines storage and Redis logs. Disabling a persistence protection is not a WordPress setting.
4. READONLY: confirm node role and write endpoint. Changing a password does not make a replica a suitable destination.