Troubleshooting guide for Lindy AI agent errors. Lindy agents fail at specific points in the workflow: trigger reception, action execution, condition evaluation, or exit condition evaluation. This guide covers each failure class.
Symptoms: No task created when webhook is sent Causes & Solutions:
| Cause | Diagnostic | Fix |
|---|---|---|
| Wrong URL | Check webhook URL in agent config | Copy exact URL from trigger settings |
| Missing auth | curl -v shows 401 |
Add Authorization: Bearer <secret> header |
| Agent inactive | Dashboard shows agent paused | Activate the agent |
| Filter blocking | Trigger filter too restrictive | Review filter conditions, test with broader filter |
| Wrong HTTP method | Using GET instead of POST | Lindy webhooks require POST |
# Diagnostic: Test webhook connectivity
curl -v -X POST "https://public.lindy.ai/api/v1/webhooks/YOUR_ID" \
-H "Authorization: Bearer YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{"test": true}'
# Expect: 200 OK
Symptoms: Emails arrive but agent does not wake up Solutions:
Symptoms: Agent did not run at scheduled time Solutions:
| Error | Cause | Fix |
|---|---|---|
| Channel not found | Channel name wrong or private | Use exact channel name; ensure bot is invited |
| Not authorized | Slack token expired | Re-authorize Slack in Lindy integrations |
| Rate limited | Too many messages | Reduce trigger frequency or batch messages |
| Error | Cause | Fix |
|---|---|---|
| Authentication expired | OAuth token expired | Re-authorize Gmail in Settings |
| Recipient rejected | Invalid email address | Validate email format in prior step |
| Draft not found | Thread ID mismatch | Verify thread context in action config |
| Error | Cause | Fix |
|---|---|---|
| Connection refused | Target API down | Verify target URL is reachable |
| 401 Unauthorized | Auth header misconfigured | Check Authorization header value |
| Timeout | Target API slow | Increase timeout or optimize target endpoint |
| SSL error | Invalid certificate | Ensure target uses valid HTTPS cert |
# Diagnostic: Test target API independently
curl -v -X POST "https://api.yourapp.com/endpoint" \
-H "Content-Type: application/json" \
-d '{"test": true}'
| Error | Cause | Fix |
|---|---|---|
| Import error | Library not available | Use only pre-installed libraries (pandas, numpy, etc.) |
| Type error | Input variable is string | Cast explicitly: int(var), json.loads(var) |
| Timeout | Long-running computation | Optimize code; avoid infinite loops |
| Return value empty | No return statement |
Add explicit return with result data |
| Cause | Fix |
|---|---|
| Fuzziness at 0 (keyword only) | Increase to 100 for semantic search |
| Content not indexed | Trigger Resync Knowledge Base action |
| Query too vague | Switch field to AI Prompt mode with specific instructions |
| File too large (>20MB) | Split into smaller files |
Cause: Exit conditions never satisfied Fix: Add measurable, achievable exit conditions:
Primary: "Found at least 3 relevant results"
Fallback: "Made 5 search attempts without finding results"
Cause: Ambiguous condition prompt Fix: Make conditions mutually exclusive with clear criteria:
Branch A: "Go down this path if the email mentions billing, payment, or invoice"
Branch B: "Go down this path if the email mentions a technical issue, bug, or error"
Branch C: "Go down this path for all other topics"
Symptom: "Task using more resources than expected" pause Cause: Agent step consuming too many credits (complex reasoning) Fix: Simplify prompt, reduce available skills (2-4 max), use smaller model
| Error Category | HTTP Status | Retry? | Notes |
|---|---|---|---|
| Auth failure | 401 | No | Re-authorize integration |
| Rate limited | 429 | Yes | Wait for credit reset |
| Agent not found | 404 | No | Verify agent exists and is active |
| Action timeout | 504 | Yes | Simplify step or increase timeout |
| Run Code error | 500 | Maybe | Fix code, then retry |
| Credit exhausted | 402 | No | Upgrade plan or wait for monthly reset |
Proceed to lindy-debug-bundle for comprehensive diagnostics.