Common Failure Modes
This page catalogs frequent errors encountered on the Ema platform, organized by category: general errors, workflow errors, external tool calling errors, Custom Code Agent errors, Voice AI issues.
General Errors
| Error / Symptom | Root Causes | How to Address |
|---|
| User unable to login with a magic link or OAuth | (1) User is trying to use an expired magic link -- login links expire after 15 minutes. (2) User is trying to use a link that has already been used. (3) User has not been invited to the tenant. (4) User is logging in from the wrong URL (e.g., customer.ema.co vs demo.ema.co). | (1) Request a new magic link and use it within 15 minutes. (2) Request a fresh link -- each link is single-use. (3) Ask a Workspace Admin or Manager to invite the user to the correct tenant. (4) Confirm the correct login URL for the target environment. |
| User is not getting a magic login link | (1) The user's company is blocking Ema's emails or sending them to spam. (2) The user is from a geo-blocked country. | (1) Check spam/junk folders. Whitelist Ema's sending domain in the company's email security settings. (2) Confirm whether the user's region is supported. Contact Ema support if a geo-block exception is needed. |
Workflow Errors
| Error / Symptom | Root Causes | How to Address |
|---|
| The output of the workflow was empty | (1) No workflow created for specific categories in a categorizer. (2) No output published for a workflow branch. | (1) Ensure every category in the categorizer -- including Fallback -- has a corresponding workflow branch. (2) Verify that all workflow paths terminate at WORKFLOW_OUTPUT and that the final agent's output is correctly mapped. |
| Error / Symptom | Root Causes | How to Address |
|---|
| Can't see tools from connected apps in External Tool Caller agent | Tool may not be enabled for AI Employees. | On the Integrations page, select the app (e.g., Jira), open the Tools tab, and enable the specific tool you want to make available to AI Employees. |
| Tool calls failing | App may not be connected, or the tool is not enabled. | Check app connections from the Integrations page. If connected, enable the tools to be available for AI Employees. |
| "I'm unable to complete this request at the moment, but we're continuously expanding our capabilities. Please contact your administrator for further assistance." | The correct action may not yet be available, or the agent is selecting the incorrect action. | If the action is available, the issue is likely the agent not selecting the right tool. Add more specific instructions in the External Tool Caller agent to guide tool selection. |
| "Sorry, it looks like your request took longer than expected. Please try again in a moment." | The connected app is experiencing high latency, crossing the timeout threshold. | Check the status of the app's APIs and confirm they are operational. Retry after the app recovers. |
| "I'm unable to complete your request to [action type] at the moment. Please try again shortly." | HITL (Human-in-the-Loop) may be disabled, and the agent needs more information from the user. | Turn on HITL for the tool. If you do not want Ema to always pause, enable HITL but turn off the "pause always" setting. |
| "Looks like [App Name] is currently down or under maintenance. Please try again shortly." | The connected app is unavailable. | Check the app's status page. Retry when the app is back online. |
Custom Code Agent Errors
| Error / Symptom | Root Causes | How to Address |
|---|
| Custom Code Agent execution fails with a runtime error | (1) Syntax error in the provided code. (2) The code references an unavailable library or module. (3) The code exceeds the execution timeout. | (1) Review the code in the Custom Code Agent configuration panel. Check for syntax issues, missing imports, or unsupported language features. (2) Confirm that only supported standard libraries are used. Custom external dependencies are not available in the sandboxed execution environment. (3) Optimize the code to run within the timeout window. Break complex logic into smaller steps across multiple agents if needed. |
| Custom Code Agent returns unexpected output format | The code produces output that does not match the expected schema for downstream agents. | Verify that the output matches the data type expected by the next agent in the workflow. Use explicit type casting or structured output (JSON) to ensure compatibility. Test the agent in isolation before wiring it into a larger workflow. |
Voice AI Errors
| Error / Symptom | Root Causes | How to Address |
|---|
| Voice AI Employee not responding to calls | (1) SIP trunk configuration is incorrect or incomplete. (2) The Voice AI Employee is not in an active state. | (1) Verify the SIP endpoint configuration in the Voice AI Employee settings. Ensure the phone number and trunk are correctly provisioned. (2) Check that the AI Employee status is active and the voice trigger is enabled. |
| Poor transcription accuracy | (1) Audio quality is low (background noise, poor microphone). (2) The caller's accent or language is not well-supported by the speech-to-text model. | (1) Advise callers to use a quiet environment and a high-quality microphone. (2) If accuracy is consistently poor for a specific language or accent, contact Ema support to discuss model tuning options. |
| Voice AI Employee responds with long latency | (1) The downstream workflow is complex, adding processing time. (2) The speech-to-text or text-to-speech service is experiencing high load. | (1) Simplify the workflow for voice interactions -- minimize the number of agent hops between the voice trigger and the response. (2) If latency persists, contact Ema support to investigate service-level performance. |
Debugging Tips
- Check AI Employee status -- Confirm the AI Employee is active and ready.
- Review trigger configuration -- Ensure the trigger type matches the interaction mode (chat, voice, document, email, scheduled).
- Identify AI Employee type -- Dashboard AI Employees debug differently from chat/voice. Dashboard rows trigger workflow runs, not conversations.
- Trace execution -- Use the execution trace to identify where the workflow fails.
- Inspect inputs -- Verify that inputs are reaching agents correctly and that types are compatible.
- Check integrations -- Confirm that connectors are authenticated and the external service is operational.
- Review categorizer -- Ensure the categorizer has all category edges, including Fallback.
- Verify Workflow Outputs -- Confirm that all branching paths lead to Workflow outputs being set.
- Validate types -- Check that all connections are type-compatible. Use
conversation_to_search_query when converting chat conversations to search inputs.
- Check audit log -- Review the audit log for recent configuration changes that may have introduced the issue. See Administration.
- Review version history -- If the issue appeared after a recent change, use version history to compare the current workflow configuration against a previous working version.
Related Pages
- Support -- How to contact Ema support and what to include in your request.
- EmaFusion™ Setup -- Model capability mismatch errors and resolution.