From retellai-pack
Diagnose and fix Retell AI voice agent errors: call failures, webhook issues, voice quality. Use when encountering Retell AI errors, debugging call issues, or troubleshooting agents. Trigger with phrases like "retell error", "call failed", "voice agent not working", "retell debug".
How this skill is triggered — by the user, by Claude, or both
Slash command
/retellai-pack:retellai-common-errorsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Quick reference for the top Retell AI errors and their solutions.
Quick reference for the top Retell AI errors and their solutions.
retell-sdk installedRetellError: 401 — Invalid API key
Fix: Verify API key in Retell Dashboard. Ensure RETELL_API_KEY starts with key_.
RetellError: 400 — Invalid phone number format
Fix: Use E.164 format: +14155551234. Both from_number and to_number must be valid.
Call connected but agent says nothing
Fix: Check LLM configuration:
const llm = await retell.llm.retrieve(agent.response_engine.llm_id);
console.log(`Model: ${llm.model}`);
console.log(`Prompt length: ${llm.general_prompt.length} chars`);
// Ensure general_prompt is not empty and gives clear instructions
Function call to https://your-api.com/endpoint timed out
Fix: Your function endpoint must respond within 5 seconds. Offload heavy work:
app.post('/functions/lookup', async (req, res) => {
// Respond immediately with acknowledgment
const result = await quickLookup(req.body.args);
res.json({ result: `Found: ${result.name}` });
// Do NOT run async work before responding
});
No webhook events received after call
Fix: Set webhook_url on the agent, not just in Dashboard settings:
await retell.agent.update(agentId, {
webhook_url: 'https://your-app.com/webhooks/retell',
});
Agent voice sounds robotic/choppy
Fix: Check network latency to Retell servers. Use a voice optimized for your use case. Try different voice IDs.
| HTTP Code | Meaning | Retryable |
|---|---|---|
| 400 | Bad request | No — fix params |
| 401 | Invalid API key | No — fix key |
| 404 | Agent/call not found | No — fix ID |
| 429 | Rate limited | Yes — backoff |
| 500+ | Server error | Yes — retry |
For debugging, see retellai-debug-bundle.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub flight505/skill-forge --plugin retellai-pack