How to Fix "Error Establishing a Redis Connection" in WordPress

The WordPress error establishing a Redis connection means the object-cache integration could not complete a usable connection to the Redis server configured for the site. WordPress may still load if the integration fails open, but object-cache reads and writes will not work until the connection problem is corrected.

Why This Happens

1. The Redis server is not running

The Redis process may have stopped, failed during a restart, or never started after the host rebooted. A containerized Redis instance can also be healthy at the container level while repeatedly restarting because its configuration, volume permissions, or memory limits are invalid.

If nothing is listening at the configured endpoint, the WordPress Redis client usually reports a refused connection or a timeout.

2. The host or port is wrong

Most WordPress Redis integrations read WP_REDIS_HOST and WP_REDIS_PORT from wp-config.php. A hostname left over from another environment, a container service name that cannot resolve from the PHP container, or a port that differs from Redis's listening port will send the client to the wrong endpoint.

The default TCP port is 6379, but it is not safe to assume every deployment uses it.

3. The socket type does not match

Redis can accept TCP connections, Unix socket connections, or both. A Unix socket is a filesystem path such as /run/redis/redis.sock; it is not a hostname. Conversely, 127.0.0.1:6379 is a TCP endpoint and must not be passed to a client configured for Unix sockets.

Even when the socket path is correct, the PHP worker must be able to see that path and have permission to access it. This is especially important when PHP and Redis run in separate containers, because a socket file is not shared unless both containers mount the same volume.

4. The Redis password is incorrect

When Redis requires authentication, the value supplied through WP_REDIS_PASSWORD must match the server configuration. A rotated secret, an extra quote copied into an environment variable, or a password set on Redis but omitted from WordPress will cause authentication to fail.

Redis 6 and later can also use ACL users. In that setup, a password alone may be insufficient if the integration is authenticating as the wrong user.

5. Redis reached its memory limit

The maxmemory setting caps the memory Redis may use. Once the cap is reached, behavior depends on maxmemory-policy. An eviction policy can remove eligible keys to make space; noeviction instead rejects writes with an out-of-memory error.

This is not a TCP connection failure, but some WordPress cache integrations surface a failed cache write or failed readiness check as a generic Redis connection error. Memory pressure can therefore produce the same visible symptom while PING still succeeds.

6. The object-cache drop-in is stale or corrupted

Persistent object caching is activated by wp-content/object-cache.php, a drop-in usually installed by a Redis cache plugin. That file loads before normal plugins. If it is partially written, belongs to an older plugin release, or remains after its plugin was removed, it can call incompatible code or use obsolete configuration.

Updating the plugin does not always guarantee that the drop-in was replaced, particularly when filesystem permissions prevent WordPress from writing to wp-content.

Diagnosing the Cause

Start from the WordPress runtime, not from your laptop. Network and DNS behavior must be tested from the same host or container that runs PHP.

Ask the integration for its view of the connection:
```
wp redis status
```
Record the client, host, port, status, and any exception text. If WP-CLI cannot bootstrap WordPress, inspect the PHP error log as well.
Test Redis directly with the same endpoint:
```
redis-cli -h redis -p 6379 ping
```
A healthy unauthenticated endpoint returns PONG. If authentication is required, avoid putting a password directly in shell history. Set it temporarily in a protected environment or use the interactive client, then run AUTH followed by PING.
Inspect the effective constants in wp-config.php:
```
define('WP_REDIS_HOST', 'redis');
define('WP_REDIS_PORT', 6379);
define('WP_REDIS_PASSWORD', 'replace-with-the-managed-secret');
```
Check for duplicate definitions, environment-specific overrides, typographical errors, and constants declared after the line that stops editing. Confirm that the hostname resolves from the PHP runtime.
If a Unix socket is configured, verify that it exists in the PHP filesystem and that the PHP user can read and write it. Compare the configured path with Redis's unixsocket setting rather than guessing.
Check the Redis service logs for startup failures, authentication errors, rejected connections, and out-of-memory messages. Then inspect memory state:
```
redis-cli INFO memory
redis-cli INFO stats
redis-cli CONFIG GET maxmemory
redis-cli CONFIG GET maxmemory-policy
```
In the output, compare used_memory with maxmemory, review evicted_keys, and look for rejected_connections. On a managed Redis service, use its console or metrics if configuration commands are disabled.
Finally, compare wp-content/object-cache.php with the drop-in shipped by the installed Redis plugin. The plugin's status screen or WP-CLI command often identifies a missing or mismatched drop-in.

Fixing Each Cause

Start Redis and fix the service failure

Restart Redis through the service manager or container orchestrator, then inspect its logs rather than treating the restart as the permanent fix. Correct invalid configuration, permissions, failed volume mounts, or resource limits before confirming that redis-cli ping and wp redis status both succeed.

Correct the TCP endpoint

Set WP_REDIS_HOST to a hostname resolvable from PHP and WP_REDIS_PORT to the port Redis actually listens on. In containers, 127.0.0.1 refers to the PHP container itself; use the Redis service name unless both processes intentionally share a network namespace.

Align socket and transport settings

Choose either TCP or a Unix socket and configure both sides consistently. For a socket, mount its directory into the PHP runtime and grant the PHP user access. For separate hosts or ordinary multi-container deployments, TCP is usually the simpler boundary.

Synchronize authentication

Update WP_REDIS_PASSWORD from the authoritative secret, or configure the integration's supported ACL username and password pair. Reload PHP workers if the value comes from an environment variable that is captured only at process startup. Never disable authentication merely to hide a credential mismatch on a network-accessible Redis server.

Resolve memory pressure

Confirm that cached keys are the intended workload before increasing maxmemory. Remove unrelated data, allocate an appropriate memory limit, and select an eviction policy suitable for cache data. If noeviction is deliberate, monitor capacity early enough to prevent rejected writes. Re-test a cache set operation, because PING alone does not prove writes work.

Refresh the object-cache drop-in

Use the Redis plugin's disable and enable commands or documented drop-in installation action to regenerate wp-content/object-cache.php. Back up a customized drop-in before replacing it. Confirm file ownership allows future updates, and remove the drop-in only when persistent object caching is intentionally disabled.

Preventing It From Happening Again

Monitor both connectivity and usable cache operations. Alert on Redis process restarts, connection failures, memory approaching maxmemory, evictions, and rejected writes. Keep the Redis plugin and its object-cache.php drop-in in sync during deployments, and test the connection from PHP after secret rotations or network changes.

Nova runs each tenant in an isolated Kubernetes namespace with managed WordPress hosting, including daily automated backups and managed core/plugin updates. You can also view plans or talk to the team about a specific Redis or caching issue.

FAQ

Will WordPress work if Redis is down?

Often, yes: many object-cache integrations fail open and let WordPress query its database directly. That behavior depends on the drop-in and configuration, however, and the site may become slower or overload its database under traffic.

Does `PONG` prove the WordPress connection is healthy?

No. PONG proves that a Redis endpoint accepted that client's connection. WordPress can still have a different hostname, invalid credentials, an incompatible socket configuration, or writes rejected by a memory policy.

Is it safe to delete `object-cache.php`?

Deleting the drop-in disables persistent object caching and may restore access when the file is broken, but it is a diagnostic or intentional disable action, not a complete repair. Regenerate the correct drop-in through the plugin after fixing the underlying problem.

Should Redis be exposed to the public internet?

No. Keep Redis on a private network or local socket, restrict which workloads can reach it, and require appropriate authentication. A firewall is an additional boundary, not a substitute for correct Redis security.