> ## 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.

# Connection Issues

> Troubleshooting Redis connectivity, network problems, and authentication errors.

## 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:

```bash theme={null}
# 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:**

```bash theme={null}
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:

```bash theme={null}
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:

```python theme={null}
# 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:

```bash theme={null}
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.