Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sluice.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Redis connection refused

[sluice] Redis connection refused at redis://localhost:6379/0.
         Redis may not be running or the URL is incorrect.
         See: https://docs.sluice.sh/troubleshooting/connection-issues
Causes:
  • Redis isn’t running on the specified host/port
  • The REDIS_URL points to a different host than your Celery broker
  • Firewall rules block access from the agent container to Redis
Fix:
  1. Verify Redis is running: redis-cli -h your-redis-host ping (should return PONG)
  2. Check that the URL matches your Celery broker_url setting
  3. If running the agent in Docker, ensure the container can reach Redis (use --network host or configure Docker networking)

​
Redis AUTH failed

[sluice] Redis AUTH failed. Permission denied.
         See: https://docs.sluice.sh/troubleshooting/connection-issues
Fix: Include credentials in the Redis URL: 
# With password only (Redis 5 and earlier)
redis://:yourpassword@redis-host:6379/0

# With username and password (Redis 6+ ACL)
redis://sluice:yourpassword@redis-host:6379/0
If your Redis uses ACLs, the Sluice user needs read access to Celery keys. Minimum permissions: 
ACL SETUSER sluice on >password ~celeryev.* ~_kombu.binding.* ~celery-task-meta-* ~unacked ~unacked_index +subscribe +psubscribe +get +llen +scard +zcard +hgetall +scan +info
Also grant access to your queue name keys (e.g., ~default ~payments ~notifications).

​
Agent can’t reach Sluice API

sluice-agent | Failed to send events to Sluice API: connection refused
sluice-agent | Retrying in 5s...
The agent needs outbound HTTPS access to sluice.sh:443. Check from inside the agent container: 
docker exec sluice-agent wget -q -O- https://sluice.sh/api/health
If this fails, check:
  • The container has DNS resolution and internet access
  • No corporate proxy is blocking outbound HTTPS
  • Firewall allows egress to sluice.sh on port 443

​
SSL/TLS errors

[sluice] SSL certificate verify failed.
This typically happens in environments with custom CA certificates (corporate proxies, self-signed certs). Fix for SDK: Set the SSL_CERT_FILE or REQUESTS_CA_BUNDLE environment variable to point to your CA bundle. Fix for agent: Mount your CA certificates into the container: 
docker run -d \
  --name sluice-agent \
  -v /etc/ssl/certs:/etc/ssl/certs:ro \
  -e SLUICE_API_KEY=sk_live_... \
  -e REDIS_URL=redis://your-redis:6379/0 \
  ghcr.io/sluice-sh/agent:latest

​
Broker disconnect and reconnection

The agent automatically reconnects to Redis with exponential backoff if the connection drops. You’ll see logs like: 
sluice-agent | Redis connection lost. Reconnecting in 1s...
sluice-agent | Redis connection lost. Reconnecting in 2s...
sluice-agent | Redis connection lost. Reconnecting in 4s...
sluice-agent | Reconnected to Redis. Resuming event subscription.
During the disconnect window:
  • Events published to Redis PUB/SUB are lost (PUB/SUB is fire-and-forget — this is a Redis limitation, not a Sluice limitation)
  • Queue depth polling resumes immediately on reconnect
  • The agent reconciles state by scanning Redis keys after reconnection
If reconnection fails repeatedly, check that Redis is healthy and that the network path between the agent and Redis is stable.

​
Multiple Celery apps sharing one Redis

If multiple Celery applications use the same Redis instance, the agent discovers all of them. This can cause:
  • Events from unrelated applications appearing in your dashboard
  • Queue names colliding across applications
Fix: Use different Redis databases for each Celery app: 
# App 1
broker_url = "redis://redis-host:6379/0"

# App 2
broker_url = "redis://redis-host:6379/1"
Then configure the agent’s REDIS_URL to point to the specific database for the application you want to monitor.

​
Redis Sentinel and Cluster

V0 supports standalone Redis connections only. Redis Sentinel and Redis Cluster topologies are not yet supported. Workaround for Sentinel users: Connect to the current master node directly by specifying its host and port in REDIS_URL. You can find the master address by running: 
redis-cli -h your-sentinel-host -p 26379 SENTINEL get-master-addr-by-name mymaster
Use the returned host:port in your Redis URL. Note that if a failover occurs, you’ll need to update the URL to point to the new master (or restart the agent, which is why native Sentinel support matters). Native Sentinel and Cluster support is planned for a future release.