Cache (Redis/Valkey)

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.

This guide covers how to configure Redis within Langfuse and what to keep in mind when bringing your own Redis.

Official and Community Support

Langfuse works with Redis and Redis-compatible stores. We distinguish between officially supported and community-supported options:

Managed services that run Redis or Valkey, such as Amazon ElastiCache, Azure Cache for Redis, and GCP 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 — 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.

Cache Configuration Options

Langfuse supports caching for API keys and prompts to improve performance. The following environment variables control caching behavior:

OR

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.

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

Amazon ElastiCache, Azure Cache for Redis, and GCP Memorystore 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:

REDIS_CONNECTION_STRING=redis://username:password@your-redis-endpoint:6379

For Redis cluster mode, enable cluster support:

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.

Redis on Kubernetes (Helm)

Bitnami offers Helm Charts for Redis and Valkey. We use the Valkey chart as a dependency for Langfuse K8s. See Langfuse on Kubernetes (Helm) for more details on how to deploy Langfuse on Kubernetes.

Example Configuration

For a minimum production setup, we recommend to use the following values.yaml overwrites when deploying the Valkey Helm chart:

valkey:
  deploy: true
  architecture: standalone
  primary:
    extraFlags:
      - "--maxmemory-policy noeviction" # Necessary to handle queue jobs correctly
  auth:
    password: changeme

Set the following environment variables to connect to your Redis instance:

REDIS_CONNECTION_STRING=redis://default:changeme@<chart-name>-valkey-master:6379/0

Docker

You can run Redis in a single Docker container. As there is no redundancy, this is not recommended for production workloads.

Example Configuration

Start the container with

docker run --name redis \
  -p 6379:6379 \
  redis --requirepass myredissecret --maxmemory-policy noeviction

Set the following environment variables to connect to your Redis instance:

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:

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

Example Configurations

AWS ElastiCache Redis Cluster

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

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:

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:

REDIS_TLS_KEY_PASSPHRASE=your-key-passphrase

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:

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

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

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.

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

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. 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 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 — Valkey is the default in our Kubernetes (Helm) deployment. If you notice diverging behavior between Redis and Valkey, please create a GitHub issue.