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.

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

{
  "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

{
  "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

{
  "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.