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

# Common Errors

> Error messages you might encounter and how to fix them — following the Sluice error format.

All Sluice errors follow the format: `[sluice] {what happened}. {why}. See: {URL}`. This page covers the most common ones, grouped by where they appear.

## SDK errors

### API key is empty

```
[sluice] API key is empty. Pass api_key= or set SLUICE_API_KEY env var.
         See: https://docs.sluice.sh/troubleshooting/api-key
```

**Cause:** `sluice.init()` was called without an API key, and the `SLUICE_API_KEY` environment variable isn't set.

**Fix:** Either pass the key directly or set the env var:

```python theme={null}
# Option 1: Direct
sluice.init(api_key="sk_live_...")

# Option 2: Environment variable
# export SLUICE_API_KEY=sk_live_...
sluice.init()
```

### Connection ID is empty

```
[sluice] Connection ID is empty. Pass connection_id= or set SLUICE_CONNECTION_ID env var.
         Find your connection ID in the Sluice dashboard under Connections.
         See: https://docs.sluice.sh/troubleshooting/connection-id
```

**Fix:** Find your connection ID in the dashboard under **Connections** and pass it to `init()` or set `SLUICE_CONNECTION_ID`.

### Connection ID is not a valid UUID

```
[sluice] Connection ID is not a valid UUID. Got: 'my-connection'.
         Find your connection ID in the Sluice dashboard under Connections.
         See: https://docs.sluice.sh/troubleshooting/connection-id
```

**Cause:** You passed the connection name instead of the UUID. Connection IDs are UUIDs like `550e8400-e29b-41d4-a716-446655440000`.

### init() called multiple times

```
[sluice] init() called multiple times. Only the first call takes effect.
```

**Cause:** `sluice.init()` was called more than once. This is a warning, not an error — the SDK works correctly using the first call's configuration.

**Fix:** Remove duplicate `init()` calls. This commonly happens when the call is in a module that gets imported multiple times.

### Failed to set up Celery integration

```
[sluice] Failed to set up Celery integration. Monitoring will not be active.
         See: https://docs.sluice.sh/troubleshooting/setup
```

**Cause:** Something unexpected went wrong during the Celery Bootstep installation. The SDK caught the error and disabled itself — your worker runs normally without monitoring.

**Fix:** Check the full traceback in your logs. Enable debug logging for the SDK by adding `logging.getLogger('sluice').setLevel(logging.DEBUG)` before calling `init()`. Common causes:

* Celery isn't installed (`pip install celery`)
* Celery version is too old (minimum 5.3)
* Celery app isn't configured yet when `init()` runs

## API errors

### 400 — Validation error

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed schema validation.",
    "docs_url": "https://docs.sluice.sh/troubleshooting/api-errors"
  }
}
```

**Cause:** The request body doesn't match the expected schema. Check the `details` field for specific field-level errors.

### 401 — Unauthorized

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key.",
    "docs_url": "https://docs.sluice.sh/troubleshooting/api-key"
  }
}
```

**Fix:** Verify your API key is correct and that the `Authorization: Bearer sk_...` header is present.

### 429 — Daily limit exceeded

```json theme={null}
{
  "error": {
    "code": "DAILY_LIMIT_EXCEEDED",
    "message": "Daily limit reached (10,000 events).",
    "docs_url": "https://docs.sluice.sh/troubleshooting/usage-limits"
  }
}
```

**Cause:** The free tier's daily event limit has been reached. The limit resets at midnight UTC.

**Fix:** Wait for the reset, or reduce event volume by monitoring fewer workers. The `Retry-After` response header indicates seconds until the limit resets.

## Celery failure modes

The following are the top failure modes seen in production Celery deployments. Sluice detects these automatically and surfaces them in the dashboard.

### Silent task stalls

Tasks that hang indefinitely without raising an exception. This happens when a task blocks on I/O (database query, HTTP call, file lock) and never returns. Celery won't mark the task as failed unless you configure `task_time_limit`.

**Fix:** Set `task_time_limit` and `task_soft_time_limit` in your Celery config. Sluice flags tasks that exceed expected duration in the **Slow Tasks** view.

### Worker OOM kills

Workers killed by the OS out-of-memory killer. Common when tasks accumulate large objects in memory across many executions. The worker process dies silently — no Celery failure event is emitted.

**Fix:** Set `worker_max_memory_per_child` to auto-restart workers after a memory threshold. Sluice tracks worker restarts and correlates them with memory growth patterns.

### Visibility timeout duplicates

Tasks executed more than once because the broker's visibility\_timeout expired before the task completed. The broker assumes the task was lost and re-delivers it to another worker.

**Fix:** Increase `visibility_timeout` in your broker transport options to exceed your longest task runtime. Sluice detects duplicate task IDs and flags them in the **Duplicates** view.

### Prefetch blindness

Workers prefetch tasks into a local buffer (`worker_prefetch_multiplier`), making them invisible to other workers and to monitoring tools that only watch the broker queue length. Queue appears empty while tasks sit in prefetch buffers.

**Fix:** Set `worker_prefetch_multiplier` to 1 for long-running tasks, or use `-Ofair` for the worker. Sluice tracks task state transitions regardless of prefetch, so you see the real picture.

### Broker disconnect

Workers lose connection to Redis/RabbitMQ. Celery has built-in reconnection, but during the disconnect window, events are lost and tasks may be re-delivered. Sluice's agent detects Broker disconnect events and tracks reconnection timing.

**Fix:** Monitor broker health alongside worker health. Sluice correlates connection drops with task delivery gaps to identify broker stability issues.

For a deeper dive into these patterns, see [Celery Failure Modes](/concepts/celery-failure-modes).