> ## Documentation Index > Fetch the complete documentation index at: https://docs.operata.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshoot the Virtual Agent > Diagnose and fix a Heartbeat Virtual Agent that is not running, not logged in to Amazon Connect, or failing to answer synthetic calls. The Heartbeat Virtual Agent fails in three common ways: the Amazon ECS task is not running, the agent is not logged in to Amazon Connect, or the agent credentials cannot be authenticated manually. Start at the section that matches your symptom. ## Before you start * Admin access to the AWS account hosting the [Cloud Orchestrator](/docs/concepts-cloud-orchestrator) and the Virtual Agent stack. * The Virtual Agent CloudFormation stack name and the Amazon Connect instance it is bound to. * The `AgentUsername` and `AgentPassword` you set when you deployed the [Virtual Agent stack](/docs/virtual-agent). ## The Virtual Agent task is not running ### 1. Open the Virtual Agent CloudFormation stack In the AWS console, open **CloudFormation** and select the Virtual Agent stack. Open the **Resources** tab and click the physical ID of the ECS service. ### 2. Check deployments and tasks The ECS service detail page shows **Deployments and tasks**. A healthy service shows `1/1` — one task running out of one desired. If the count is `0/1`, the task is stopped or failing to start. Continue to step 3. ### 3. Inspect the failing task Open the **Tasks** tab on the service. Click into the most recent task. The **Stopped reason** and **Containers** sections explain why the task exited. The most common causes: * **Image pull failure** — the task can't reach the Operata container registry. Confirm the VPC the stack deploys into has outbound internet access (NAT gateway or VPC endpoints). * **Insufficient task CPU or memory** — bump the task definition's resource allocation and update the service. * **Container exit on startup** — the agent crashed before logging in. Continue to "The Virtual Agent is not logged in" below to read the logs. You can stop and start the Virtual Agent from this view by updating the service's desired task count. ## The Virtual Agent is not logged in The fastest check is the Amazon Connect console — the real-time agent metrics show the Virtual Agent as logged in once login succeeds. If the metrics show the agent offline, read the ECS logs. ### 1. Open the Virtual Agent ECS service In the AWS console, open **CloudFormation** and select the Virtual Agent stack. Under **Resources**, expand the `VirtualAgent` resource and click through to the ECS cluster the stack created. ### 2. Open the logs Click the service — named `VirtualAgent` — and select the **Logs** tab. The log lines describe the login flow: | Log line | Meaning | | ------------------------------------------- | --------------------------------------------------------------------------------------- | | `Logging in using native CCP` | Non-SSO login attempt. | | `Logging in using SSO Provider: ` | SSO login attempt. | | `logged in successfully` | Login succeeded. The agent is ready to answer Heartbeat calls. | | `Failed to login` | Login failed. The Virtual Agent retries; multiple failures may appear before a success. | A long-running service may also show repeated `logged in successfully` entries from session refreshes — that is normal. ### 3. Match the failure to a cause | Failure line near a `Failed to login` | Likely cause | Recovery | | ------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | | `Authentication failed` (non-SSO) | The `AgentPassword` is wrong, or the user is disabled in Amazon Connect. | Reset the password in Amazon Connect, redeploy the stack with the new value. | | `Authentication failed` (SSO) | The IDP rejected the credentials, or MFA is enforced. | Confirm the IDP login works in a browser. Exclude the user from MFA enforcement. | | `Timed out waiting for CCP` | The VPC can't reach the CCP URL, or the URL is wrong. | Confirm `CCPUrl` matches the Amazon Connect instance and is reachable from the VPC. | | `Routing profile not allowed` | The user has `Operata_Heartbeat_RP` assigned. | Remove the routing profile from the Virtual Agent user. | ## The Virtual Agent ID cannot be authenticated manually The third step is to confirm the Virtual Agent's credentials work outside ECS — this isolates Amazon Connect or IDP issues from ECS networking issues. ### 1. Non-SSO instances Open the Amazon Connect CCP URL in a browser. Sign in with the `AgentUsername` and `AgentPassword` you set in the Virtual Agent CloudFormation stack. The agent should reach the **Ready** state. If sign-in fails, reset the password in Amazon Connect and redeploy the Virtual Agent stack with the new `AgentPassword`. ### 2. SSO instances Open the `LoginUrl` you set in the Virtual Agent stack in a browser. Sign in with the `AgentUsername` and the IDP password for that user. The agent should redirect to Amazon Connect and reach **Ready**. If sign-in fails: * The IDP login is broken — fix it in the IDP first. * MFA is enforced on the Virtual Agent user — exclude the user from MFA enforcement (for example, in Azure Security Defaults). ## Verify Run a Heartbeat test from the Operata console. The test call dials the Heartbeat phone number, the Virtual Agent answers within seconds, and the run completes within the Heartbeat call duration (typically under 30 seconds). The run appears on the [Operata console](https://app.operata.io) and on your EventBridge bus. If the Virtual Agent still does not answer after working through this page, contact [Operata Support](mailto:support@operata.com) with the ECS service ARN, the most recent task ID, and the relevant log extract. ## Related * [Deploy the Heartbeat Virtual Agent](/docs/virtual-agent) — redeploy the stack if you changed parameters. * [Set up Heartbeat](/docs/heartbeat-setup) — confirm the routing profile, contact flow, and phone number bindings. * [Concept: Cloud Orchestrator](/docs/concepts-cloud-orchestrator) — the runtime the Virtual Agent answers calls inside of. * [Troubleshoot the AWS integration](/docs/aws-troubleshooting) — for CTR and Amazon EventBridge-related failures on the same AWS account.