Worker Troubleshooting

"No API key found"

Fix: Set api_key in your YAML config, or set CUEAPI_API_KEY env var, or run cueapi login.

"At least one handler must be defined"

Your config file has no handlers or the handlers section is empty.

Fix: Add at least one handler to your config:

handlers:
  my-task: "python3 handler.py"

Worker running but not picking up executions

Common causes:

1. Task mismatch — payload.task doesn't match any handler key
2. No worker transport cues — Cues are using webhook transport, not worker
3. Wrong API key — Worker is authenticated as a different user

Debug:

# Check what's claimable
curl https://api.cueapi.ai/v1/executions/claimable \
  -H "Authorization: Bearer cue_sk_YOUR_KEY"
 
# Verify your cue uses worker transport
cueapi get cue_xxx

Handler script not found

Error: [Errno 2] No such file or directory: 'handler.py'

Fix: Use absolute paths or set cwd in the handler config:

handlers:
  my-task:
    cmd: "python3 handler.py"
    cwd: "/home/user/scripts"

Handler timeout

Error: Handler timed out after 300s

Fix: Increase the timeout in handler config:

handlers:
  my-task:
    cmd: "python3 slow_task.py"
    timeout: 600  # 10 minutes

Template variables not resolving

If {{ payload.field }} appears as a literal string in your env vars, check:

1. Your payload contains the expected field
2. The template syntax is correct (double curly braces, no spaces around dots)
3. Nested fields use dot notation: {{ payload.config.key }}

Connection errors

Error: Connection refused to api.cueapi.ai

Fix:

1. Check your internet connection
2. Verify the API is up: curl https://api.cueapi.ai/status
3. Check if you need to configure a proxy

Worker heartbeat failures

If the worker can't send heartbeats, it will log warnings but continue running. Executions may not be routed to this worker.

Fix: Check network connectivity and API key validity.