> Source: https://builder.ema.ai/v2/troubleshooting/common-failures > Title: Common Failure Modes # Common Failure Modes This page is a symptom-to-fix reference for the issues you're most likely to encounter on the Ema platform. It's organized by area — sign-in, permissions, workflow runs, knowledge bases, tools, and Autopilot — so you can jump straight to the category that matches what you're seeing. Each entry names the symptom, the likely cause, and the concrete fix. Every claim here reflects how the platform actually behaves. Error wording shown in quotes is the message you'll see; where the cause is environment-specific, the fix tells you what to confirm rather than inventing a code. ## Sign-in and authentication Ema signs you in by email first. After you enter your email, the platform resolves how your account authenticates and shows the right next step: - **One-time passcode (OTP)** — Ema emails you a six-character code to verify. - **Password** — only in deployments where password sign-in is enabled. - **Single sign-on (SSO)** — you're redirected to your organization's identity provider (SAML 2.0 or OIDC, such as Okta or Google). If your account has two-factor authentication (2FA) enabled, you'll then enter a time-based code from your authenticator app (TOTP), or a backup code. > [INFO] > Ema does not use "magic link" sign-in. If a document or old runbook refers to a login link, the current flow is the email-plus-code (OTP) or SSO flow described here. Symptom Likely cause Fix **"No account found for this email address."** The email isn't a member of any tenant, or it's mistyped. Sign-in resolves your tenant from your email. Confirm the exact address you were invited with. If it's correct and still fails, ask a user admin or system admin to invite or reactivate you. See [User management](/builder/v2/administration/user-management). **The sign-in code says it's expired** A one-time sign-in code is valid only for a limited window after it's sent. By default this is ~10 minutes. Select **Request a new code** and enter the new code promptly. The sign-in screen shows a live countdown so you know how long a code has left. See [Account lockout and sign-in code limits](#account-lockout-and-sign-in-code-limits) for the exact windows. **The sign-in code is rejected even though it looks right** The code was already used, you're entering an older code after requesting a newer one, or there's a typo. Each code is single-use, and requesting a new code invalidates the previous one. Always use the most recent code in your inbox. Request a fresh one if unsure, and enter that one. **"Too many code requests" or "Too many incorrect attempts" — the sign-in form is temporarily locked** Too many code requests or too many failed verification attempts in a short window triggers a temporary soft lock (a `RATE_LIMITED` response). See [Account lockout and sign-in code limits](#account-lockout-and-sign-in-code-limits) for the defaults. Wait for the countdown on the lock screen to finish, then try again. Retrying during the lock doesn't shorten it. **No sign-in code email arrives** The message is in spam/junk, your mail security is quarantining it, or delivery to your address failed. Check spam and quarantine first. Ask IT to allow mail from Ema's sending domain. If it still doesn't arrive, contact [support](/builder/v2/troubleshooting/support) with the time you requested it. **SSO doesn't redirect, or returns an error from your IdP** SSO isn't configured for the tenant, the identity provider settings are wrong, or your IdP account isn't entitled to the app. This is an administrator setup issue, not something you can fix from the sign-in screen. Ask a system admin to review the SSO configuration — see [Tenant and SSO](/builder/v2/administration/tenant-and-sso). **2FA code (TOTP) won't verify** Your authenticator's clock has drifted, or you're entering an old 30-second code. Wait for the next code and enter it quickly. If you've lost the device, use a backup code — select **Use a backup code instead** on the verification step. A used backup code resets your 2FA enrollment and prompts you to set up an authenticator again. **You were signed in but got logged out** Access tokens are short-lived (15 minutes by default) and are refreshed automatically; sessions end after the refresh window (7 days by default) or when you sign out elsewhere. Sign in again. If you're being logged out far more often than expected, capture the timestamps and contact [support](/builder/v2/troubleshooting/support). ### Account lockout and sign-in code limits To stop guessing and email-flooding, Ema rate-limits one-time sign-in codes per account, per tenant. Hitting either limit — too many requests, or too many wrong codes — triggers a temporary **soft lock**: the sign-in form returns a `RATE_LIMITED` response and won't accept a new request or code until the lock expires. Nothing about your account is permanently disabled; the lock simply clears on its own. By default: - A one-time sign-in code is valid for **~10 minutes** after it's generated. After that you must request a new one. - Within a **10-minute** rolling window you can request up to **3 codes** before a further request locks the form, and the **3rd** failed code (or two-factor) verification triggers the lock. - Hitting either limit triggers a **~10-minute soft lock**. The lock clears automatically; waiting it out is the only fix — retrying during the lock doesn't shorten it. A successful sign-in clears your failed-attempt counter, and requesting a new code invalidates the previous one (each code is single-use). These are deployment-configurable defaults. An operator can tune them per deployment through the auth service configuration: Setting Default Controls `EMU_OTP_TTL_MINUTES` `10` How long a one-time sign-in code stays valid after it's generated. `EMU_OTP_MAX_REQUESTS_PER_WINDOW` `3` How many sign-in codes can be requested per rate-limit window before a soft lock. `EMU_OTP_MAX_FAILED_ATTEMPTS` `3` How many failed code (or two-factor) verifications are allowed per window before a soft lock. `EMU_OTP_RATE_LIMIT_WINDOW_MINUTES` `10` The length of the rolling window the request and failed-attempt counts are measured over. `EMU_OTP_SOFT_LOCK_DURATION_MINUTES` `10` How long the soft lock lasts once a limit is exceeded. > [INFO] > If your deployment uses values other than these defaults, your administrator can tell you the exact windows. The sign-in screen's countdown always reflects the live, configured values, so trust the on-screen timer over any fixed number. ## Permissions and access Access in Ema is governed by **roles**. If a button is missing or an action returns "forbidden," the usual cause is that your role doesn't include that capability — not a bug. The roles you'll encounter are `system_admin`, `env_admin`, `builder_admin`, `user_admin`, `builder`, `user`, and `no_access`. See [Governance and permissions](/builder/v2/administration/governance-and-permissions) for the full capability map. Symptom Likely cause Fix **You can't see Workflows or AI Employees** You have an end-user role (`user`), which doesn't include building. Ask an administrator to grant a builder role (`builder`, `builder_admin`, `system_admin`, or `env_admin`). **You can build, but can't create connections or knowledge bases** Source connections and knowledge bases are admin-only. The plain `builder` role selects from existing knowledge bases but can't create them or handle credentials. Ask a system admin or builder admin to create the connection or knowledge base, then select it when configuring your AI Employee. See [Knowledge bases](/builder/v2/core-concepts/knowledge-bases). **You can't manage users, SSO, or API keys** These are administrator capabilities. User management requires `user_admin` (or higher); SSO requires `system_admin`; API key creation requires `system_admin` or `builder_admin`. Ask an administrator with the right role, or have your role elevated. See [Administration](/builder/v2/administration). **"maximum number of active user API keys reached" (or "...system API keys reached")** Personal (user) keys are capped at 5 per user; system-level keys are capped at 50 per tenant. Revoke a key you no longer use before creating a new one. Manage keys under **Admin > API keys**. See [Authentication](/builder/v2/api-reference/authentication). **You can open an AI Employee but not edit or run it** Access to a specific AI Employee is checked per request against its access list. You may have read access without being a member who can edit or run. Ask the AI Employee's owner or an administrator to add you to its access list. The creator, and tenant administrators, always have access. ## Workflow run failures When an AI Employee runs, the workflow service executes its workflow as a sequence of typed nodes and records a **run** with a status and a step-by-step trace. A run ends in one of these states: Status Meaning `pending` Accepted, not yet started. `running` Actively executing. `paused` Waiting on a human — a human-in-the-loop (HITL) step or a tool that needs approval or input. `completed` Finished and produced its output. `failed` Stopped on an error before completing. `cancelled` Aborted, by a user or the system. `skipped` Not executed (for example, a branch that wasn't taken). The first move for any run problem is to open the run and read its **step trace** — the per-step record of what each node received and returned. From an AI Employee, open the run from its runs list to reach the run detail page. See [Debug logs](/builder/v2/testing-operations/debug-logs) for how to read a trace. Symptom Likely cause Fix **The AI Employee doesn't run at all from its live trigger** No version is published, or the trigger doesn't match how it's being invoked. Publish a version, then confirm the trigger type matches the call. Runs record their trigger — `ui`, `api`, `schedule`, `webhook`, `feedback`, or `document`. See [Launching and monitoring](/builder/v2/testing-operations/launching-and-monitoring). **The run failed at a specific step** That node hit an error — bad input shape, a downstream service error, or a tool failure. Open the step in the trace and read its input and error. Fix the upstream node that produced the bad input, or the failing tool's configuration, then re-run. **The run completed but the output is empty or wrong** A branch produced no output, or a step received input of the wrong type, so it had nothing useful to act on. Trace backward from the output node. Confirm every branch that can be taken terminates in an output, and that each node's input maps to a real value of the expected type from an earlier step. **The run is stuck in `paused`** A human-in-the-loop step or a tool that requires approval is waiting for a person to respond. Respond to the pending HITL prompt or tool approval. If the request is stale, an administrator can abort the run (see below). See [Human-in-the-loop](/builder/v2/core-concepts/human-in-the-loop). **You need to stop a run that's hung or looping** A run in `pending`, `running`, or `paused` can be aborted. On the run detail page, administrators (system admin, builder admin, or env admin) see an **Abort run** button. Aborting moves the run to `cancelled`. **The model "couldn't serve the request" / capability mismatch** A step needs a model capability the tenant's available models don't cover, or a bring-your-own-model deployment doesn't include the required model. Review the model configuration for the tenant. See [EmaFusion™](/builder/v2/emafusion) for how model selection and availability work. ## Knowledge base ingestion A knowledge base (KB) is built by ingesting documents — either uploaded files or files pulled from a connected source (SharePoint, Google Drive, Confluence, Box, or ServiceNow). Ingestion runs as a durable, orchestrated pipeline: extract text, chunk it, embed it, and store it for retrieval. Each document carries an ingestion status, so a document that isn't searchable usually hasn't finished — or has failed — ingestion. Typical document statuses you'll see: **pending** (queued), **processing** (extracting, chunking, or embedding), **processed** (searchable), and **failed**/**error** (ingestion didn't complete). > [INFO] > Creating connections and knowledge bases, uploading files, and triggering syncs are administrator actions. As a builder you select from existing knowledge bases and scope them with a folder filter. If you need a new source or KB, ask an administrator. Symptom Likely cause Fix **A document never becomes searchable; it sits in `processing`** Ingestion is still working through extraction/embedding — large PDFs are slow — or a step is retrying. Give it time, especially for large files. If it's stuck far longer than comparable documents, an administrator should check the source connection and re-trigger the sync. Re-ingesting a document upserts it in place, so the document keeps its identity. **A document shows `failed` / error** The file couldn't be extracted (unsupported or corrupt format), or a downstream step errored. Confirm the file is a supported type and not corrupt. Re-upload or re-sync. If a specific file fails repeatedly, contact [support](/builder/v2/troubleshooting/support) with the file type and the document name. **New or changed source files aren't showing up** The sync hasn't run yet, or the changed files fall outside the KB's configured scope (folder filter). Have an administrator trigger a manual sync and confirm the connector scope includes the folders you expect. Sync runs are recorded with document counts you can review. **The connector won't connect, or syncs stop working** OAuth consent was revoked or expired, or credentials changed at the source. SharePoint, Confluence, Box, and Google Drive authenticate via an OAuth consent flow. An administrator should re-authenticate the connection. For SharePoint, an admin-consent grant may be required at the identity provider. See [Data connectors](/builder/v2/integrations-data/data-connectors). **Retrieval returns nothing for a query you expect to match** The relevant documents aren't `processed` yet, the folder filter is excluding them, or the KB isn't attached to the AI Employee. Confirm the documents are processed, widen or correct the folder filter, and check the KB is selected on the AI Employee. See [Knowledge bases](/builder/v2/core-concepts/knowledge-bases). **You can't upload to a connector-backed KB** Direct uploads are for local-file knowledge bases; connector-backed KBs are populated by syncing the source. Add the content at the source and sync, or use a local-file KB for ad-hoc uploads. ## Tool and integration calls AI Employees can call **Tools** — operations exposed by connected apps or built as custom integrations. When a step that calls a tool fails, the cause is usually that the tool isn't available to AI Employees, the integration isn't connected, or the external service is unhealthy. Symptom Likely cause Fix **A tool you expect isn't available to the AI Employee** The integration isn't connected, or the specific tool isn't enabled for use by AI Employees. On the **Integrations** page, open the integration and enable the tools you want AI Employees to use. See [Integrations hub](/builder/v2/integrations-data/integrations-hub). **A tool call fails or times out** The connected app is slow, down, or rejecting the request; or credentials have expired. Check the connected app's status and that the integration is still authenticated. Retry once the app recovers. Read the failing step's error in the run trace for the specifics. **A custom (HTTP or script) Tool returns the wrong shape** The Tool's output doesn't match the output schema the next node expects. Open the Tool in the Tool editor, test it in isolation, and align its output schema with what downstream nodes consume. See [The Tool editor](/builder/v2/integrations-data/the-tool-editor). **A tool call pauses waiting for input you didn't expect** The tool is configured for human-in-the-loop, so it pauses for approval or missing information. Respond to the prompt, or adjust the tool's HITL setting if you don't want it to pause every time. See [Human-in-the-loop](/builder/v2/core-concepts/human-in-the-loop). ## Autopilot unavailable or degraded Autopilot is Ema's in-app assistant. It's enabled per tenant, and it surfaces a banner when the service is under load rather than failing silently. Symptom Likely cause Fix **The Autopilot button is missing and the shortcut does nothing** Autopilot isn't enabled for your tenant yet — it's gated by the `agent_panel_enabled` flag. Contact your administrator or Ema support to have it turned on. See [Autopilot — limits, availability, and troubleshooting](/builder/v2/autopilot/limits-availability-and-troubleshooting). **"Autopilot is under heavy traffic"** The service is busy; responses may be slower than usual. Keep working — requests still go through. The banner clears on its own when load drops. **"Autopilot is temporarily unavailable"** The service is at capacity. The composer is locked until it recovers. Wait for the retry hint, then send again. The banner reflects fleet health, not your account — your work isn't lost. **Can't start a new chat** You're at the limit on concurrent running Autopilot sessions. The **New chat** control is disabled with the note "Session limit reached." Close a running session in the recent chats list to free a slot, then start a new one. **Autopilot won't take a new message in a session** A turn is already running in that session — one turn at a time per session. Wait for the turn to finish, or use **Stop**, then send. For the complete Autopilot reference — known limits, load banners, exporting and resuming sessions — see [Autopilot: limits, availability, and troubleshooting](/builder/v2/autopilot/limits-availability-and-troubleshooting). ## When you can't isolate the cause If the run trace, statuses, and connection checks don't point to a cause, gather what you've found and contact support. The single most useful thing you can capture is the **run ID** (shown on the run detail page) plus the failing step — it lets the team trace the exact execution. See [Support](/builder/v2/troubleshooting/support) for what to include. ## What's next - [Support](/builder/v2/troubleshooting/support) — how to reach Ema and what to send. - [Debug logs](/builder/v2/testing-operations/debug-logs) — read a run's step trace. - [Governance and permissions](/builder/v2/administration/governance-and-permissions) — what each role can do. - [Audit log](/builder/v2/administration/audit-log) — find recent configuration changes that may have introduced an issue.