--- title: "Cache (Redis/Valkey) Configuration (Self-Hosted)" sidebarTitle: Redis / Valkey description: "Configure Redis or Valkey as a caching layer and queue for self-hosted Langfuse. Includes Redis environment variables, connection options, and configuration best practices." label: "Version: v4" --- # Cache (Redis/Valkey) This is a deep dive into Redis/Valkey configuration. Follow one of the [deployment guides](/self-hosting#deployment-options) to get started. Langfuse uses Redis/Valkey as a caching layer and queue. It is used to accept new events quickly on the API and defer their processing and insertion. This allows Langfuse to handle request peaks gracefully. You can use a managed service on AWS, Azure, or GCP, or host it yourself. At least version 7 is required and the instance must have `maxmemory-policy=noeviction` configured. For Langfuse v4, Redis 7.2 is recommended — see the [v3 to v4 upgrade guide](/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4#step-1). This guide covers how to configure Redis within Langfuse and what to keep in mind when bringing your own Redis. ## Official and Community Support [#support] Langfuse works with Redis and Redis-compatible stores. We distinguish between officially supported and community-supported options: | Option | Support Level | | -------------------------------------------------------------- | ------------- | | [Redis](https://redis.io/) (>= 7, self-hosted or managed) | Official | | [Valkey](#valkey-vs-redis) (>= 8, self-hosted or managed) | Official | | Other Redis-compatible stores (e.g., Dragonfly, KeyDB, Garnet) | Community | Managed services that run Redis or Valkey, such as [Amazon ElastiCache](https://aws.amazon.com/elasticache/redis/), [Azure Cache for Redis](https://azure.microsoft.com/en-us/products/cache/), and [GCP Memorystore](https://cloud.google.com/memorystore), are covered by the official support level. - **Official**: Maintained and tested by the Langfuse team. We prioritize bug reports for these options. - **Community**: Expected to work based on community usage. We do not systematically test these options; support is best-effort and fixes often depend on community contributions. In either case, please report problems via [GitHub issues](/issues) — pull requests that fix or improve support for community-supported options are highly welcome. ## Configuration Langfuse accepts the following environment variables to fine-tune your Redis usage. They need to be provided for the Langfuse Web and Langfuse Worker containers. | Variable | Required / Default | Description | | ------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | | `REDIS_CONNECTION_STRING` | Required | Redis connection string with format `redis[s]://[[username][:password]@][host][:port][/db-number]` | ### Cache Configuration Options Langfuse supports caching for API keys and prompts to improve performance. The following environment variables control caching behavior: | Variable | Required / Default | Description | | ------------------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LANGFUSE_CACHE_API_KEY_ENABLED` | `true` | Enable or disable API key caching. Set to `false` to disable caching of API keys. Plain-text keys are never stored in Redis, only hashed or encrypted keys. | | `LANGFUSE_CACHE_API_KEY_TTL_SECONDS` | `300` | Time-to-live (TTL) in seconds for cached API keys. Determines how long API keys remain in the cache before being refreshed. | | `LANGFUSE_CACHE_PROMPT_ENABLED` | `true` | Enable or disable prompt caching. Set to `false` to disable caching of prompts. | | `LANGFUSE_CACHE_PROMPT_TTL_SECONDS` | `300` | Time-to-live (TTL) in seconds for cached prompts. Determines how long prompts remain in the cache before being refreshed. | OR | Variable | Required / Default | Description | | ------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REDIS_HOST` | Required | Redis host name. | | `REDIS_PORT` | `6379` | Port of the Redis instance. | | `REDIS_USERNAME` | | Username for Redis authentication. | | `REDIS_AUTH` | | Authentication string for the Redis instance. | | `REDIS_TLS_ENABLED` | `false` | Enable TLS for the Redis connection. Alternatively, enable tls via `rediss://` connection string. | | `REDIS_TLS_CA_PATH` | | Path to the CA certificate for the Redis connection. | | `REDIS_TLS_CERT_PATH` | | Path to the certificate for the Redis connection. | | `REDIS_TLS_KEY_PATH` | | Path to the private key for the Redis connection. | | `REDIS_TLS_SERVERNAME` | | Server name for SNI (Server Name Indication). Useful when connecting to Redis through a proxy or with custom certificates. | | `REDIS_TLS_REJECT_UNAUTHORIZED` | `true` | Set to `false` to disable certificate validation. Not recommended for production. When not set, defaults to Node.js secure behavior. | | `REDIS_TLS_CHECK_SERVER_IDENTITY` | | Set to `false` to bypass server identity checking. Use with caution in enterprise environments with custom certificate setups. | | `REDIS_TLS_SECURE_PROTOCOL` | | TLS protocol version specification (e.g., `TLSv1_2_method`, `TLSv1_3_method`). Uses Node.js defaults when not specified. | | `REDIS_TLS_CIPHERS` | | Custom cipher suite configuration. Allows specification of allowed TLS ciphers for enhanced security requirements. | | `REDIS_TLS_HONOR_CIPHER_ORDER` | | Set to `true` to use server's cipher order preference instead of client's. Useful for enforcing security policies. | | `REDIS_TLS_KEY_PASSPHRASE` | | Passphrase for encrypted private keys. Required if your TLS private key is password-protected. | | `REDIS_KEY_PREFIX` | `` | Optional prefix for all Redis keys to avoid key collisions with other applications. Should end with `:`. | | `REDIS_CLUSTER_ENABLED` | `false` | Set to `true` to enable Redis cluster mode. When enabled, you must also provide `REDIS_CLUSTER_NODES`. | | `REDIS_CLUSTER_NODES` | | Comma-separated list of Redis cluster nodes in the format `host:port`. Required when `REDIS_CLUSTER_ENABLED` is `true`. | | `REDIS_CLUSTER_SLOTS_REFRESH_TIMEOUT` | `5000` | Timeout in milliseconds for the Redis cluster slots refresh operation. Increase this value if you experience timeout errors during cluster topology updates. | | `REDIS_SENTINEL_ENABLED` | `false` | Set to `true` to enable Redis Sentinel mode. Cannot be enabled simultaneously with cluster mode. | | `REDIS_SENTINEL_NODES` | | Comma-separated list of Redis Sentinel nodes in the format `host:port`. Required when `REDIS_SENTINEL_ENABLED` is `true`. | | `REDIS_SENTINEL_MASTER_NAME` | | Name of the Redis Sentinel master. Required when `REDIS_SENTINEL_ENABLED` is `true`. | | `REDIS_SENTINEL_USERNAME` | | Username for Redis Sentinel authentication (optional). | | `REDIS_SENTINEL_PASSWORD` | | Password for Redis Sentinel authentication (optional). | | `REDIS_SENTINEL_TLS_ENABLED` | `false` | Set to `true` to also apply TLS to the connections to the Sentinel nodes, in addition to the Redis master/replica connections. Requires `REDIS_TLS_ENABLED=true`; otherwise it is ignored. Only relevant when `REDIS_SENTINEL_ENABLED` is `true`. | ### Timeout Configuration Langfuse applies a socket-level watchdog to every Redis connection it opens: if a connection is expecting data and receives none for 30 seconds, the client destroys the socket and reconnects. This prevents hung connections from blocking BullMQ worker concurrency slots indefinitely. Connections additionally use a fixed TCP keep-alive of 10 seconds to prevent middleboxes from killing idle connections. | Variable | Required / Default | Description | | ------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `REDIS_SOCKET_TIMEOUT_MS` | `30000` | Socket timeout in milliseconds for all Redis connections (web and worker, including BullMQ queue connections). Set to `0` to disable the watchdog. Positive values must be at least `10000`: BullMQ blocking commands (`BZPOPMIN`) legitimately idle for ~5 seconds between packets, and lower values cause healthy idle workers to cycle through reconnects. | #### Troubleshooting: `Socket timeout. Expecting data, but didn't receive any in 30000ms.` This error is raised by the client-side watchdog described above, not by the Redis server — a healthy Redis instance does not rule it out. Common causes: - **CPU starvation of the Langfuse container (most common):** if the Node.js event loop stalls, e.g. because the worker container is CPU-throttled, incoming Redis data is not processed in time and the watchdog fires even though Redis responded promptly. Increase the CPU allocation of the affected container — this has resolved the error for multiple self-hosted deployments even when average CPU utilization appeared low. - **Network middleboxes:** NAT gateways, proxies, or firewalls that silently drop connections between Langfuse and Redis. Raising `REDIS_SOCKET_TIMEOUT_MS` only lengthens the watchdog; it does not address CPU starvation and delays recovery from genuinely hung connections. ## Deployment Options This section covers different deployment options and provides example environment variables. ### Managed Redis/Valkey by Cloud Providers [#managed-redis-valkey] [Amazon ElastiCache](https://aws.amazon.com/de/elasticache/redis/), [Azure Cache for Redis](https://azure.microsoft.com/de-de/products/cache/), and [GCP Memorystore](https://cloud.google.com/memorystore/?hl=en) are fully managed Redis services. Langfuse handles failovers between read-replicas and supports Redis cluster mode for horizontal scaling. For **standalone Redis instances**, use the standard configuration: ```bash REDIS_CONNECTION_STRING=redis://username:password@your-redis-endpoint:6379 ``` For **Redis cluster mode**, enable cluster support: ```bash REDIS_CLUSTER_ENABLED=true REDIS_CLUSTER_NODES=your-cluster-endpoint:6379 REDIS_AUTH=your-redis-password # if authentication is enabled ``` Ensure that your Langfuse container can reach your Redis instance within the VPC. You must set the parameter `maxmemory-policy` to `noeviction` to ensure that the queue jobs are not evicted from the cache. ### Redis on Kubernetes (Helm) The [Langfuse Helm chart](/self-hosting/deployment/kubernetes-helm) can deploy a cache for you via `redis.deploy: true`. From chart version `v2.0.0` onwards it bundles the [valkey-io/valkey](https://github.com/valkey-io/valkey) chart and wires Langfuse to it automatically, including credentials. This bundled instance is a single Valkey pod and is intended for smaller deployments. For high availability, set `redis.deploy: false` and point Langfuse at an external Redis or Valkey cluster, for example a [managed service](#managed-redis-valkey). #### Example Configuration ```yaml redis: deploy: true auth: # Leave the password empty to have the chart generate one, or point # auth.existingSecret at a secret you manage. password: changeme ``` For an external instance, set `redis.deploy: false` and provide the connection details: ```yaml redis: deploy: false host: your-redis-endpoint port: 6379 auth: existingSecret: my-redis-secret existingSecretPasswordKey: password ``` Whichever option you choose, make sure `maxmemory-policy` is set to `noeviction` on the instance so that queue jobs are not evicted. ### Docker You can run Redis in a single [Docker](https://hub.docker.com/_/redis/) container. As there is no redundancy, this is **not recommended for production workloads**. #### Example Configuration Start the container with ```bash docker run --name redis \ -p 6379:6379 \ redis --requirepass myredissecret --maxmemory-policy noeviction ``` Set the following environment variables to connect to your Redis instance: ```yaml REDIS_HOST=localhost REDIS_PORT=6379 REDIS_AUTH=myredissecret ``` ## Redis Cluster Mode Redis cluster mode enables horizontal scaling by distributing data across multiple Redis nodes. Langfuse supports Redis cluster mode for high-availability and increased throughput scenarios. ### Configuration To enable Redis cluster mode, set the following environment variables: ```bash REDIS_CLUSTER_ENABLED=true REDIS_CLUSTER_NODES=redis-node1:6379,redis-node2:6379,redis-node3:6379,redis-node4:6379,redis-node5:6379,redis-node6:6379 REDIS_AUTH=your-redis-password # if authentication is enabled ``` For production deployments, we recommend using 3 master nodes with 1 replica each (6 nodes total) for high availability. ### Example Configurations #### AWS ElastiCache Redis Cluster ```bash REDIS_CLUSTER_ENABLED=true REDIS_CLUSTER_NODES=clustercfg.my-redis-cluster.abc123.cache.amazonaws.com:6379 REDIS_AUTH=your-auth-token REDIS_TLS_ENABLED=true REDIS_TLS_SERVERNAME=clustercfg.my-redis-cluster.abc123.cache.amazonaws.com ``` #### Self-hosted Redis Cluster ```bash REDIS_CLUSTER_ENABLED=true REDIS_CLUSTER_NODES=10.0.1.10:6379,10.0.1.11:6379,10.0.1.12:6379,10.0.1.13:6379,10.0.1.14:6379,10.0.1.15:6379 REDIS_AUTH=your-cluster-password ``` #### Enterprise Redis with Custom CA Certificates For enterprise environments with custom certificate authorities and specific TLS requirements: ```bash REDIS_CONNECTION_STRING=redis://username:password@redis.example.com:6379 REDIS_TLS_ENABLED=true REDIS_TLS_CA_PATH=/app/ca/cacertbundle.pem REDIS_TLS_CERT_PATH=/app/redis-certs/tls.crt REDIS_TLS_KEY_PATH=/app/redis-certs/tls.key REDIS_TLS_SERVERNAME=redis.example.com REDIS_TLS_REJECT_UNAUTHORIZED=true ``` This configuration enables: - Proper certificate validation against a custom CA - SNI support via `REDIS_TLS_SERVERNAME` for proxied connections - Secure certificate verification without global workarounds For encrypted private keys, add: ```bash REDIS_TLS_KEY_PASSPHRASE=your-key-passphrase ``` When using Redis cluster mode: - Ensure all cluster nodes are accessible from your Langfuse containers - Use the same authentication credentials across all cluster nodes - Monitor cluster health and handle node failures appropriately - Set `maxmemory-policy=noeviction` on all cluster nodes to prevent queue job eviction - Set `LANGFUSE_INGESTION_QUEUE_SHARD_COUNT` to a positive integer to enable sharding of the ingestion queue across cluster nodes. We recommend 2-3x of your Redis shards. - Set `LANGFUSE_TRACE_UPSERT_QUEUE_SHARD_COUNT` to a positive integer to enable sharding of the trace upsert queue across cluster nodes. We recommend 2-3x of your Redis shards. ## Redis Sentinel Mode Redis Sentinel provides high availability for Redis deployments without the complexity of full cluster mode. It automatically monitors Redis master and replica instances, handles failover, and provides service discovery. This makes it ideal for deployments that need automatic failover but don't require horizontal scaling across multiple shards. ### Configuration To enable Redis Sentinel mode, set the following environment variables: ```bash REDIS_SENTINEL_ENABLED=true REDIS_SENTINEL_NODES=sentinel1:26379,sentinel2:26379,sentinel3:26379 REDIS_SENTINEL_MASTER_NAME=mymaster REDIS_AUTH=your-redis-password # if authentication is enabled on Redis REDIS_SENTINEL_PASSWORD=your-sentinel-password # if authentication is enabled on Sentinels (optional) ``` ### Example Configurations #### Self-hosted Redis with Sentinel ```bash REDIS_SENTINEL_ENABLED=true REDIS_SENTINEL_NODES=10.0.1.10:26379,10.0.1.11:26379,10.0.1.12:26379 REDIS_SENTINEL_MASTER_NAME=langfuse-master REDIS_AUTH=your-redis-password ``` When using Redis Sentinel mode: - Ensure all Sentinel nodes are accessible from your Langfuse containers - The `REDIS_SENTINEL_MASTER_NAME` must match the master name configured in your Sentinel setup - Set `maxmemory-policy=noeviction` on the Redis master and replicas to prevent queue job eviction - By default, `REDIS_TLS_ENABLED` applies TLS only to the connections to the Redis master and replica instances. To also encrypt the connections to the Sentinel nodes, set `REDIS_SENTINEL_TLS_ENABLED=true` (see below). ### TLS with Sentinel When `REDIS_TLS_ENABLED=true`, Langfuse applies TLS to the connections to the Redis master and replica instances, but not to the connections to the Sentinel nodes. If your Sentinel nodes also require encrypted connections, set `REDIS_SENTINEL_TLS_ENABLED=true`. The same TLS options that configure the Redis connection (`REDIS_TLS_CA_PATH`, `REDIS_TLS_CERT_PATH`, `REDIS_TLS_KEY_PATH`, `REDIS_TLS_SERVERNAME`, and the other `REDIS_TLS_*` variables) are then reused for the Sentinel connections. ```bash REDIS_SENTINEL_ENABLED=true REDIS_SENTINEL_NODES=10.0.1.10:26379,10.0.1.11:26379,10.0.1.12:26379 REDIS_SENTINEL_MASTER_NAME=langfuse-master REDIS_AUTH=your-redis-password REDIS_TLS_ENABLED=true # required if REDIS_SENTINEL_TLS_ENABLED=true REDIS_SENTINEL_TLS_ENABLED=true ``` ## Detecting a Stalled Worker [#worker-liveness] Redis-level disruptions that invalidate BullMQ job locks — key eviction under a non-`noeviction` memory policy, a `FLUSHALL`, or a failover — can leave the worker container running while it silently stops consuming all queues. The worker health endpoint provides an opt-in check (`?failIfQueueConsumptionStuck=true`) that fails once no jobs have been processed for a configurable period, so a liveness probe can restart the container automatically. See [Health and Readiness Check Endpoints](/self-hosting/configuration/health-readiness-endpoints) for details. ## Sizing Recommendations Langfuse uses Redis mainly for queuing event metadata that should be processed by the worker. In most cases, the worker can process the queue quickly to keep events from piling up. For every ~100000 events per minute we recommend about 1GB of memory for the Redis instance. ## Redis Permissions Redis allows users to restrict the keys and commands that a given user can access [Redis ACL Docs](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/). Langfuse expects that the provided user has access to all keys and commands within the given database, i.e. the access control should be defined as `on ~* +@all`. ## Valkey vs Redis [#valkey-vs-redis] [Valkey](https://github.com/valkey-io/valkey) was created as an open source (BSD) alternative to Redis. It is a drop-in replacement for Redis and is compatible with the Redis protocol. According to the maintainers, major version 8.0.0 retains compatibility to Redis v7 in most instances. Both are [officially supported](#support) — Valkey is the default in our [Kubernetes (Helm)](/self-hosting/deployment/kubernetes-helm) deployment. If you notice diverging behavior between Redis and Valkey, please create a [GitHub issue](/issues). --- If you experience any issues when self-hosting Langfuse, please: 1. Check out [Troubleshooting & FAQ](/self-hosting/troubleshooting-and-faq) page. 2. Use [Ask AI](/ask-ai) to get instant answers to your questions. 3. Ask the maintainers on [GitHub Discussions](/gh-support). 4. Create a bug report or feature request on [GitHub](/issues). Enterprise-grade support is available when self-hosting Langfuse. Learn more on our [pricing page](/pricing-self-host). --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/self-hosting/deployment/infrastructure/cache.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .