{ "schema_version": 2, "id": "operate/rs/databases/connect/troubleshooting-guide", "title": "Troubleshooting pocket guide for Redis Software", "url": "https://redis.io/docs/latest/operate/rs/databases/connect/troubleshooting-guide/", "summary": "Troubleshoot issues with Redis Software, including connectivity issues between the database and clients or applications.", "tags": [ "docs", "operate", "rs" ], "last_updated": "2026-09-24T09:16:24+01:00", "page_type": "content", "content_hash": "262f2d77bdbcaa68a51edaf317357e0f801a610ed974db4fe023ff7bf90015fb", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "If your client or application cannot connect to your database, verify the following." }, { "id": "identify-redis-host-issues", "title": "Identify Redis host issues", "role": "content", "text": "#### Check resource usage\n\n- Used disk space should be less than `90%`. To check the host machine's disk usage, run the [`df`](https://man7.org/linux/man-pages/man1/df.1.html) command:\n\n [code example]\n\n- RAM and CPU utilization should be less than `80%`, and host resources must be available exclusively for Redis Software. You should also make sure that swap memory is not being used or is not configured.\n\n 1. Run the [`free`](https://man7.org/linux/man-pages/man1/free.1.html) command to check memory usage:\n\n [code example]\n\n 1. Used CPU should be less than `80%`. To check CPU usage, use `top` or `vmstat`.\n\n Run [`top`](https://man7.org/linux/man-pages/man1/top.1.html):\n\n [code example]\n\n Run [`vmstat`](https://man7.org/linux/man-pages/man8/vmstat.8.html):\n\n [code example]\n\n 1. If CPU or RAM usage is greater than 80%, ask your system administrator which process is the culprit. If the process is not related to Redis, terminate it.\n\n#### Sync clock with time server\n\nIt is recommended to sync the host clock with a time server.\n\nVerify that time is synchronized with the time server using one of the following commands:\n\n- `ntpq -p`\n\n- `chronyc sources`\n\n- [`timedatectl`](https://man7.org/linux/man-pages/man1/timedatectl.1.html)\n\n#### Remove https_proxy and http_proxy variables\n\n1. Run [`printenv`](https://man7.org/linux/man-pages/man1/printenv.1.html) and check if `https_proxy` and `http_proxy` are configured as environment variables:\n\n [code example]\n\n1. If `https_proxy` or `http_proxy` exist, remove them:\n\n [code example]\n [code example]\n\n#### Review system logs\n\nReview system logs including the syslog or journal for any error messages, warnings, or critical events. See [Logging](https://redis.io/docs/latest/operate/rs/clusters/logging) for more information." }, { "id": "identify-issues-caused-by-security-hardening", "title": "Identify issues caused by security hardening", "role": "content", "text": "- Temporarily deactivate any security hardening tools (such as selinux, cylance, McAfee, or dynatrace), and check if the problem is resolved. \n\n- The user `redislabs` must have read and write access to `/tmp` directory. Run the following commands to verify.\n\n 1. Create a test file in `/tmp` as the `redislabs` user:\n [code example]\n\n 1. Verify the file was created successfully:\n [code example]\n\n- Using a non-permissive file mode creation mask (`umask`) can cause issues.\n\n 1. Check the output of `umask`:\n\n [code example]\n\n 1. If `umask`'s output differs from the default value `0022`, it might prevent normal operation. Consult your system administrator and revert to the default `umask` setting." }, { "id": "identify-cluster-issues", "title": "Identify cluster issues", "role": "content", "text": "- Use `supervisorctl status` to verify all processes are in a `RUNNING` state:\n\n [code example]\n\n- Run `rlcheck` and verify no errors appear:\n\n [code example]\n\n- Run [`rladmin status issues_only`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/status) and verify that no issues appear:\n\n [code example]\n\n- Run [`rladmin status shards`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/status#status-shards). For each shard, `USED_MEMORY` should be less than 25 GB.\n\n [code example]\n\n- Run [`rladmin cluster running_actions`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/cluster/running_actions) and confirm that no tasks are currently running (active):\n\n [code example]" }, { "id": "troubleshoot-connectivity", "title": "Troubleshoot connectivity", "role": "errors", "text": "#### Database endpoint resolution\n\n1. On the client machine, check if the database endpoint can be resolved:\n\n [code example]\n\n1. If endpoint resolution fails on the client machine, check on one of the cluster nodes:\n\n [code example]\n\n1. If endpoint resolution succeeds on the cluster node but fails on the client machine, review the DNS configuration and fix any errors.\n\n1. If the endpoint can’t be resolved on the cluster node, [contact support](https://redis.com/company/support/).\n\n#### Client application issues\n\n1. To identify possible client application issues, test connectivity from the client machine to the database using [`redis-cli`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/redis-cli):\n\n [`INFO`](https://redis.io/docs/latest/commands/info):\n\n [code example]\n\n [`PING`](https://redis.io/docs/latest/commands/ping):\n\n [code example]\n \n or if TLS is enabled:\n \n [code example]\n\n1. If the client machine cannot connect, try to connect to the database from one of the cluster nodes:\n\n [code example]\n\n1. If the cluster node is also unable to connect to the database, [contact Redis support](https://redis.com/company/support/).\n\n1. If the client fails to connect, but the cluster node succeeds, perform health checks on the client and network.\n\n#### Firewall access\n\n1. Run one of the following commands to verify that database access is not blocked by a firewall on the client machine or cluster:\n\n [code example]\n\n [code example]\n\n [code example]\n\n1. To resolve firewall issues:\n\n 1. If a firewall is configured for your database, add the client IP address to the firewall rules.\n\n 1. Configure third-party firewalls and external proxies to allow the cluster FQDN, database endpoint IP address, and database ports." }, { "id": "troubleshoot-latency", "title": "Troubleshoot latency", "role": "errors", "text": "#### Server-side latency\n\n- Make sure the database's used memory does not reach the configured database max memory limit. For more details, see [Database memory limits](https://redis.io/docs/latest/operate/rs/databases/memory-performance/memory-limit).\n\n- Try to correlate the time of the latency with any surge in the following metrics:\n\n - Number of connections\n\n - Used memory\n\n - Evicted keys\n\n - Expired keys \n\n- Run [`SLOWLOG GET`](https://redis.io/docs/latest/commands/slowlog-get) using [`redis-cli`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/redis-cli) to identify slow commands such as [`KEYS`](https://redis.io/docs/latest/commands/keys) or [`HGETALL`](https://redis.io/docs/latest/commands/hgetall):\n\n [code example]\n\n Consider using alternative commands such as [`SCAN`](https://redis.io/docs/latest/commands/scan), [`SSCAN`](https://redis.io/docs/latest/commands/sscan), [`HSCAN`](https://redis.io/docs/latest/commands/hscan) and [`ZSCAN`](https://redis.io/docs/latest/commands/zscan)\n\n- Keys with large memory footprints can cause latency. To identify such keys, compare the keys returned by [`SLOWLOG GET`](https://redis.io/docs/latest/commands/slowlog-get) with the output of the following commands:\n\n [code example]\n\n [code example]\n\n- For additional diagnostics, see:\n\n - [Diagnosing latency issues](https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/latency)\n\n - [View Redis slow log](https://redis.io/docs/latest/operate/rs/clusters/logging/redis-slow-log)\n\n#### Client-side latency\n\nVerify the following:\n\n- There is no memory or CPU pressure on the client host.\n\n- The client uses a connection pool instead of frequently opening and closing connections.\n\n- The client does not erroneously open multiple connections that can pressure the client or server." } ], "examples": [ { "id": "identify-redis-host-issues-ex0", "language": "sh", "code": "$ df -h\n Filesystem Size Used Avail Use% Mounted on\n overlay 59G 23G 33G 41% /\n /dev/vda1 59G 23G 33G 41% /etc/hosts", "section_id": "identify-redis-host-issues" }, { "id": "identify-redis-host-issues-ex1", "language": "sh", "code": "$ free\n total used free shared buff/cache available\n Mem: 6087028 1954664 993756 409196 3138608 3440856\n Swap: 1048572 0 1048572", "section_id": "identify-redis-host-issues" }, { "id": "identify-redis-host-issues-ex2", "language": "sh", "code": "$ top\n Tasks: 54 total, 1 running, 53 sleeping, 0 stopped, 0 zombie\n %Cpu(s): 1.7 us, 1.4 sy, 0.0 ni, 96.8 id, 0.0 wa, 0.0 hi, 0.1 si, 0.0 st\n KiB Mem : 6087028 total, 988672 free, 1958060 used, 3140296 buff/cache\n KiB Swap: 1048572 total, 1048572 free, 0 used. 3437460 avail Mem", "section_id": "identify-redis-host-issues" }, { "id": "identify-redis-host-issues-ex3", "language": "sh", "code": "$ vmstat\n procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu-----\n r b swpd free buff cache si so bi bo in cs us sy id wa st\n 2 0 0 988868 177588 2962876 0 0 0 6 7 12 1 1 99 0 0", "section_id": "identify-redis-host-issues" }, { "id": "identify-redis-host-issues-ex4", "language": "sh", "code": "printenv | grep -i proxy", "section_id": "identify-redis-host-issues" }, { "id": "identify-redis-host-issues-ex5", "language": "sh", "code": "unset https_proxy", "section_id": "identify-redis-host-issues" }, { "id": "identify-redis-host-issues-ex6", "language": "sh", "code": "unset http_proxy", "section_id": "identify-redis-host-issues" }, { "id": "identify-issues-caused-by-security-hardening-ex0", "language": "sh", "code": "$ su - redislabs -s /bin/bash -c 'touch /tmp/test'", "section_id": "identify-issues-caused-by-security-hardening" }, { "id": "identify-issues-caused-by-security-hardening-ex1", "language": "sh", "code": "$ ls -l /tmp/test\n -rw-rw-r-- 1 redislabs redislabs 0 Aug 12 02:06 /tmp/test", "section_id": "identify-issues-caused-by-security-hardening" }, { "id": "identify-issues-caused-by-security-hardening-ex2", "language": "sh", "code": "$ umask\n 0022", "section_id": "identify-issues-caused-by-security-hardening" }, { "id": "identify-cluster-issues-ex0", "language": "sh", "code": "supervisorctl status", "section_id": "identify-cluster-issues" }, { "id": "identify-cluster-issues-ex1", "language": "sh", "code": "rlcheck", "section_id": "identify-cluster-issues" }, { "id": "identify-cluster-issues-ex2", "language": "sh", "code": "$ rladmin status issues_only\n CLUSTER NODES:\n NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS\n\n DATABASES:\n DB:ID NAME TYPE STATUS SHARDS PLACEMENT REPLICATION PERSISTENCE ENDPOINT \n\n ENDPOINTS:\n DB:ID NAME ID NODE ROLE SSL \n\n SHARDS:\n DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS", "section_id": "identify-cluster-issues" }, { "id": "identify-cluster-issues-ex3", "language": "sh", "code": "$ rladmin status shards\n SHARDS:\n DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS \n db:1 db1 redis:1 node:1 master 0-16383 2.13MB OK", "section_id": "identify-cluster-issues" }, { "id": "identify-cluster-issues-ex4", "language": "sh", "code": "$ rladmin cluster running_actions\n No active tasks", "section_id": "identify-cluster-issues" }, { "id": "troubleshoot-connectivity-ex0", "language": "sh", "code": "dig ", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-connectivity-ex1", "language": "sh", "code": "dig @localhost ", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-connectivity-ex2", "language": "sh", "code": "redis-cli -h -p -a INFO", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-connectivity-ex3", "language": "sh", "code": "redis-cli -h -p -a PING", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-connectivity-ex4", "language": "sh", "code": "redis-cli -h -p -a --tls --insecure --cert --key PING", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-connectivity-ex5", "language": "sh", "code": "redis-cli -h -p -a PING", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-connectivity-ex6", "language": "sh", "code": "iptables -L", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-connectivity-ex7", "language": "sh", "code": "ufw status", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-connectivity-ex8", "language": "sh", "code": "firewall-cmd –list-all", "section_id": "troubleshoot-connectivity" }, { "id": "troubleshoot-latency-ex0", "language": "sh", "code": "redis-cli -h -p -a SLOWLOG GET ", "section_id": "troubleshoot-latency" }, { "id": "troubleshoot-latency-ex1", "language": "sh", "code": "redis-cli -h -p -a --memkeys", "section_id": "troubleshoot-latency" }, { "id": "troubleshoot-latency-ex2", "language": "sh", "code": "redis-cli -h -p -a --bigkeys", "section_id": "troubleshoot-latency" } ] }