View a markdown version of this page

Troubleshoot AgentCore Runtime - Amazon Bedrock AgentCore
My agent invocations fail with "This runtime is not MMDSv2-enabled" ValidationExceptionMy agent invocations time out with RuntimeClientError (424)My Docker build fails with "403 Forbidden" when pulling Python base imagesI get "Unknown service: 'bedrock-agent-core-runtime'" error when using boto3I get "AccessDeniedException" when trying to create an Amazon Bedrock AgentCore RuntimeMy Docker build fails with "exec /bin/sh: exec format error"What are the requirements for Docker containers used with Amazon Bedrock AgentCore Runtime?My long-running tool gets interrupted after 15 minutesMy idle sessions are not being released and I am exhausting my session quotaHow do I access the runtimeSessionId in my agent code for tagging or grouping resources?I have RuntimeClientError (403) issuesI have missing or empty CloudWatch LogsI stopped seeing CloudWatch metrics for my agent after moving to platform version V2I have payload format issuesI need help understanding HTTP error codesI need recommendations for testing my agentI need help debugging container issuesI need help troubleshooting MCP protocol agentsI need help troubleshooting bidirectional streaming using WebSocketMy code changes aren’t reflected in existing sessionsSpans are missing when my runtime is invoked from a Lambda functionMy S3 Files or EFS mount fails with "Access denied"My S3 Files or EFS mount fails with "ResourceNotFound"My S3 Files or EFS mount times outI get "Permission Denied" when writing to my mounted filesystemMy container fails to start with HTTP 424 error on high-layer imagesThe container image needs more build disk than this runtime hasServiceQuotaExceededException: maxImageSizeMb limit exceededMy agent runtime is in CREATE_FAILED or UPDATE_FAILED because of a lifecycle hookMy capacity provider is in state CREATE_FAILEDMy agents on Instances do not have access to their credentialsBest practices

Troubleshoot AgentCore Runtime

This troubleshooting topic helps you identify and resolve common issues when working with AgentCore Runtime. By following these solutions, you can quickly diagnose and fix problems with your agent runtimes.

Topics

My agent invocations fail with "This runtime is not MMDSv2-enabled" ValidationException

When this occurs: When invoking an agent runtime via InvokeAgentRuntime, ExecuteCommand, InvokeAgentRuntimeWithWebSocketStream, InvokeAgentRuntimeCommandShell, or GetAgentCard

Why this happens: Starting June 30, 2026, Amazon Bedrock AgentCore Runtime requires all agent runtimes to use MMDSv2 (MicroVM Metadata Service Version 2). The service rejects invocations targeting runtimes without metadataConfiguration set, or with requireMMDSV2 set to false or null.

Solution: Call UpdateAgentRuntime with requireMMDSV2 set to true in metadataConfiguration:

import boto3 client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') try: client.update_agent_runtime( agentRuntimeId='your-agent-runtime-id', metadataConfiguration={ 'requireMMDSV2': True } ) print("MMDSv2 enabled successfully.") except client.exceptions.ResourceNotFoundException as e: print(f"Runtime not found: {e}") except Exception as e: print(f"Error enabling MMDSv2: {e}")

After you update, new invocations will succeed. Existing sessions are not affected.

My agent invocations time out with RuntimeClientError (424)

When this occurs: During agent invocation via SDK or console, or requests through a session endpoint.

Why this happens: The application doesn’t become ready or respond within the timeout.

For session endpoint requests, these failures return HTTP 424 with RuntimeClientError in the X-Amzn-Bedrock-AgentCore-Runtime-Error header and an empty response body. For details, see Handle proxy errors.

Several factors can cause this:

  • Container issues: Make sure your server listens on the configured serving port. It must handle POST requests at the invocation path.

  • ARM64 compatibility: Your container must be ARM64 compatible

  • Retry logic: Review retry mechanisms for handling transient issues

For HTTP, the default serving port is 8080 and the default invocation path is /invocations. For configuration details, see Configure your agent’s serving port and invocation path.

My Docker build fails with "403 Forbidden" when pulling Python base images

When this occurs: During docker build or docker run when using public.ecr.aws base images

Why this happens: ECR Public authentication issues — expired or missing authentication is a common issue.

Solution: Either login to ECR Public or logout completely:

# Option 1: Login to ECR Public aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws # Option 2: Logout (recommended for avoiding token expiration) docker logout public.ecr.aws # Option 3: Use Docker Hub directly in Dockerfile FROM python:3.10-slim # instead of public.ecr.aws/docker/library/python:3.10-slim

I get "Unknown service: 'bedrock-agent-core-runtime'" error when using boto3

When this occurs: When invoking Amazon Bedrock AgentCore APIs using boto3 SDK

Why this happens: Outdated boto3 library — common issue as most installations don’t have latest SDK

Solution: Update to latest boto3 and botocore versions:

pip install --upgrade boto3 botocore # Minimum versions: boto3 1.39.8+, botocore 1.33.8+

I get "AccessDeniedException" when trying to create an Amazon Bedrock AgentCore Runtime

When this occurs: During agent creation via console, SDK, or CLI

Why this happens: Either your user lacks permissions, or the execution role isn’t properly configured for Amazon Bedrock AgentCore

Solution: Several factors can cause this:

My Docker build fails with "exec /bin/sh: exec format error"

When this occurs: When building containers for Amazon Bedrock AgentCore deployment

Why this happens: Building ARM64 containers on x86 systems without proper cross-platform setup

Solution: Build ARM64 compatible containers. You can consider using buildx for cross-platform builds. Alternatively, you can use CodeBuild. For example code, see the Amazon Bedrock AgentCore Samples.

What are the requirements for Docker containers used with Amazon Bedrock AgentCore Runtime?

Review Amazon Bedrock AgentCore Runtime requirements for full details.

In summary, your Docker container must meet these requirements:

  • Serving port: Listen on the configured serving port (8080 by default for HTTP). To make additional application ports reachable through a session endpoint, configure allowed ports.

  • Endpoint: Handle POST requests at the configured invocation path (/invocations by default for HTTP)

  • Architecture: Must be ARM64 compatible

  • Response: Should handle the expected payload format

My long-running tool gets interrupted after 15 minutes

For information, see Handle asynchronous and long-running agents with Amazon Bedrock AgentCore Runtime for full details.

When this occurs: During long-running agent operations or complex workflows

Why this happens: Amazon Bedrock AgentCore automatically terminates sessions after 15 minutes of inactivity. The platform determines activity from the /ping response: a session reporting HealthyBusy is kept alive, while a session reporting Healthy is treated as idle-eligible and its idle time is measured from when the status last changed (see the time_of_last_update field below).

Solution: Ensure your /ping endpoint returns HealthyBusy while background work is in progress:

{"status": "HealthyBusy"}

If you are using the Bedrock AgentCore SDK, the ping response is handled automatically. For custom implementations, ensure your ping handler returns HealthyBusy while processing.

My idle sessions are not being released and I am exhausting my session quota

When this occurs: Session count climbs continuously under load and sessions are not released after the idle timeout (for example, ServiceQuotaExceededException / maxVms errors during a burst of invocations), even though each session is idle.

Why this happens: When a session reports Healthy, the platform measures how long it has been idle from the time_of_last_update field in your /ping response, which must reflect when the status last changed. If your ping handler sets time_of_last_update to the current time on every ping, the reported idle time keeps resetting, which prevents the idle timeout from firing. Sessions then live until MaxLifetime and can exhaust your session quota.

Solution: Update time_of_last_update only when the status actually changes, or omit it entirely so the platform tracks status changes on its own:

{"status": "Healthy"}

If you are using the Bedrock AgentCore SDK, upgrade to the latest version, where the ping response is handled correctly. As a stopgap, calling StopRuntimeSession releases stuck sessions.

How do I access the runtimeSessionId in my agent code for tagging or grouping resources?

When this applies: You want to group, tag, or trace resources (e.g., S3 objects, logs) by the current agent runtime session.

Solutions:

  • If you’re using the Bedrock Agents SDK, use context.session_id.

  • If you’re building a custom runtime server, extract it from the X-Amzn-Bedrock-AgentCore-Runtime-Session-Id HTTP header.

Solution 1: For agents using the Bedrock Amazon Bedrock AgentCore SDK, use context.session_id from your agent entrypoint

@app.entrypoint def my_agent(payload, context): session_id = context.session_id # Use session_id for S3 object tagging/organization s3_client = boto3.client('s3') s3_client.put_object( Bucket='my-bucket', Key=f'agent-outputs/{session_id}/output.json', Body=json.dumps(result), Tagging=f'SessionId={session_id}' ) return result

Solution 2: For custom runtime HTTP servers

The runtime session ID is passed in this HTTP header. Parse it from the incoming request and use it for tagging, correlation, or downstream propagation.

X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <value>

I have RuntimeClientError (403) issues

Problem

You receive a 403 "RuntimeClientError" when attempting to invoke your agent runtime.

Causes

This error typically occurs due to:

  • Container startup failures

  • Permissions issues with execution role

  • Authentication issues with bearer token

Resolution

Follow these steps to resolve the issue:

  1. Check CloudWatch Logs : Any issues with starting up the container will reflect as a 403 - RuntimeClientError. Navigate to the following CloudWatch log group to check for startup errors:

    /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>/[runtime-logs]
  2. Verify Execution Role : Ensure your agent’s execution role has the necessary permissions. For more information, see AgentCore Runtime execution role.

  3. Validate Authentication : For MCP protocol agents, ensure your bearer token is valid and not expired.

I have missing or empty CloudWatch Logs

Problem

You encounter errors but don’t see any relevant logs in CloudWatch.

Solution

Try these approaches to diagnose the issue:

  1. Check Correct Log Group : Ensure you’re looking in the right CloudWatch log group. The standard pattern is:

    /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>/runtime-logs
  2. Run Locally for Diagnostics : If there are no CloudWatch Logs, try running the agent container locally using the exact same payload you used for invocation in AgentCore Runtime. This can help identify issues that might not be visible in the logs.

  3. Enable Verbose Logging : Update your agent code to include more detailed logging, especially around the entry points and any error handling logic.

I stopped seeing CloudWatch metrics for my agent after moving to platform version V2

Problem

You invoke an agent runtime across accounts: a principal in your account invokes a runtime owned by another account through a resource-based policy. After the runtime moves to platform version V2, you no longer see the per-invocation CloudWatch metrics in your account.

Solution

This is expected behavior, not missing data. On platform version V2, a cross-account invocation publishes the runtime metrics to the resource owner’s account, not to the calling account. The resource owner is the account that owns the agent runtime. Look for the metrics in the resource owner’s account. For more information, see AgentCore generated runtime observability data.

I have payload format issues

Problem

Your agent runtime invocation fails even though the container starts successfully.

Resolution

Follow these steps to resolve payload format issues:

  1. Verify Payload Structure : Ensure your payload structure matches what your agent expects. Pay special attention to:

    • If your agent code expects input keyword in the payload, make sure to include it:

      { "input": { "prompt": "Your question here" } }
    • Not just:

      { "prompt": "Your question here" }
  2. Check Documentation : Review the expected input format in the documentation.

I need help understanding HTTP error codes

Problem

Your agent returns HTTP error codes that are difficult to interpret.

Example error message

You may see an error like:

An error occurred (RuntimeClientError) when calling the InvokeAgentRuntime operation: Received error (<HTTP Status Code>) from runtime. Please check your CloudWatch logs for more information

Resolution

Here are the most common error codes and their meanings:

422 Unprocessable Entity

This happens when the container encounters validation issues with the input payload.

Common causes:

  • Missing required fields in the payload (e.g., missing "input" field)

  • Incorrect data types for fields

  • Invalid format for the payload

403 Forbidden

Authentication or authorization issues.

Check your bearer token or IAM permissions.

409 RetryableConflictException

A second operation reached a session while it was still being provisioned or torn down. You see the message Session operation in progress, please retry.

What it means: This is a transient, retryable conflict — not a terminal error. The window is brief. Already-running sessions are not affected.

How to fix: Retry the operation with short exponential backoff. For HTTP-based APIs (such as InvokeAgentRuntime, InvokeAgentRuntimeCommand, and StopRuntimeSession), the AWS SDKs auto-retry this when default retries are enabled. If you disabled retries or call the API directly without an AWS SDK, add the retry yourself. For WebSocket-based APIs (such as InvokeAgentRuntimeWithWebSocketStream and InvokeAgentRuntimeCommandShell), the AWS SDKs do not auto-retry. Always retry these yourself.

500 Internal Server Error

Runtime exceptions in your agent code.

Check CloudWatch logs for detailed stack traces.

I need recommendations for testing my agent

To systematically debug agent runtime issues:

Test locally first

Before deploying to AgentCore Runtime:

  • Run your agent container locally using the same Docker image

  • Verify it works with the exact same payload

Compare payloads

Ensure consistency between environments:

  • Ensure the payload structure between local testing and AgentCore Runtime invocation is identical

  • Pay special attention to nesting of fields like "input" and "prompt"

I need help debugging container issues

If you suspect container-related issues:

Pull and run locally

Test your container image on your local machine:

docker pull <your-ecr-repo-uri> docker run -p 8080:8080 <your-ecr-repo-uri>

Test with curl

Send test requests to your local container:

curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"input": {"prompt": "Hello world!"}}'

Check container logs

Examine the container’s output for errors:

docker logs <container-id>

I need help troubleshooting MCP protocol agents

For MCP protocol agents, follow these specific troubleshooting steps:

Verify endpoint path

MCP servers should listen on 0.0.0.0:8000/mcp/

Use MCP Inspector

Test with the MCP Inspector tool:

  1. Install and run the MCP Inspector: npx @modelcontextprotocol/inspector

  2. Connect to your local server at http://localhost:8000/mcp

  3. For deployed agents, use the properly URL-encoded endpoint

Authentication issues

Check authentication configuration:

  • Ensure bearer token is correctly set in the headers

  • Verify your Cognito user pool is correctly set up

I need help troubleshooting bidirectional streaming using WebSocket

For bidirectional streaming using WebSocket agents, follow these specific troubleshooting steps:

Verify endpoint configuration

For the standard Runtime WebSocket API, configure the /ws endpoint as described in HTTP protocol contract. For WebSocket connections through a session endpoint, use your application’s WebSocket path and an allowed port as described in HTTP, gRPC, and WebSocket connections.

Test locally with incremental complexity

Start with simple local testing before deploying:

  1. Test basic connection: Verify your agent accepts WebSocket connections at ws://localhost:8080/ws

  2. Test message handling: Send simple text messages and verify responses

  3. Test session management: Verify persistent conversations work as expected

  4. Test error handling: Ensure your agent gracefully handles connection drops and malformed messages

Authentication issues

Check authentication configuration for deployed agents:

  • For OAuth: Ensure bearer token is valid and not expired

  • For SigV4: Make sure input to the signing algorithm is correct, including the WebSocket URL, headers, and request method

  • Use the correct authentication method that matches your agent’s configuration

Common connection issues

Address common WebSocket connection problems:

  • Verify message format compatibility between your agent and client expectations

  • Configure message frame fragmentation or implement chunking to stay within message frame size (64 KB) and message frame rate (250 frames per second) limits to prevent connection closure

My code changes aren’t reflected in existing sessions

Problem

You’ve updated your agent runtime with new code, but existing sessions continue to use the old version.

Why this happens

Each microVM session is created with the code assets ( agentRuntimeArtifact ) that were deployed at the time of session creation. Once a session is established, it continues using that version of the code until the session terminates, even when code assets are updated as part of performing the UpdateAgentRuntime operation.

Solution

To access your updated code, use a new session ID.

Spans are missing when my runtime is invoked from a Lambda function

When this occurs: When invoking AgentCore Runtime from a Lambda function

Why this happens: Lambda generates its own X-Amzn-Trace-Id header. If the Lambda trace has Sampled=0 , this unsampled context propagates to AgentCore Runtime and the runtime skips span generation for that invocation.

Solution:

  • Enable Lambda active tracing: Turn on X-Ray active tracing on your Lambda function so that it produces sampled traces ( Sampled=1 ).

  • Verify CloudWatch Transaction Search: Ensure you have completed the setup in Configure observability and that your trace segment destination is set to CloudWatch Logs.

  • Check the sampling decision: Log the _X_AMZN_TRACE_ID environment variable inside your Lambda function. If it shows Sampled=0 , active tracing is not enabled or an upstream caller is making the sampling decision.

My S3 Files or EFS mount fails with "Access denied"

When this occurs: During invocation of an agent with S3 Files or EFS storage configured

Why this happens: The execution role is missing required filesystem permissions. For more information about configuring persistent storage, see File system configurations for AgentCore Runtime.

Solution:

For S3 Files, ensure your execution role has:

{ "Effect": "Allow", "Action": [ "s3files:ClientMount", "s3files:ClientWrite" ], "Resource": "arn:aws:s3files:<region>:<account>:file-system/*", "Condition": { "StringEquals": { "s3files:AccessPointArn": "<your-access-point-arn>" } } }

For EFS, ensure your execution role has:

{ "Effect": "Allow", "Action": [ "elasticfilesystem:ClientMount", "elasticfilesystem:ClientWrite" ], "Resource": "arn:aws:elasticfilesystem:<region>:<account>:file-system/<fs-id>", "Condition": { "StringEquals": { "elasticfilesystem:AccessPointArn": "<your-access-point-arn>" } } }

Omit s3files:ClientWrite or elasticfilesystem:ClientWrite if your agent only needs read access.

My S3 Files or EFS mount fails with "ResourceNotFound"

When this occurs: During invocation of an agent with S3 Files or EFS storage configured

Why this happens: The filesystem or access point was deleted after the agent was created, or the IDs are incorrect.

Solution:

  • Verify the filesystem exists:

    • S3 Files: aws s3files list-file-systems --region <region>

    • EFS: aws efs describe-file-systems --region <region>

  • Verify the access point exists:

    • S3 Files: aws s3files list-access-points --file-system-id <fs-id> --region <region>

    • EFS: aws efs describe-access-points --file-system-id <fs-id> --region <region>

  • Verify mount targets exist in all required availability zones:

    • S3 Files: aws s3files list-mount-targets --file-system-id <fs-id> --region <region>

    • EFS: aws efs describe-mount-targets --file-system-id <fs-id> --region <region>

    • Ensure each mount target shows Available status and is in the same VPC as the agent runtime.

  • If the resource was deleted, recreate it and update the agent runtime with the new access point ARN

My S3 Files or EFS mount times out

When this occurs: During invocation of an agent with S3 Files or EFS storage configured. The invocation may take longer than usual before failing.

Why this happens: The VPC network configuration is blocking NFS traffic (port 2049) between the agent’s compute and the filesystem mount targets.

Solution:

  • Check security groups on mount targets: Verify the security group attached to your mount targets allows inbound TCP on port 2049 from the security group used by your agent runtime

  • Check security groups on agent runtime: Verify the security group used by your agent runtime allows outbound TCP on port 2049 to the mount target security group

  • Verify mount targets exist in the correct availability zones: Mount targets must exist in the same availability zones as the subnets configured on your agent runtime:

    • S3 Files: aws s3files list-mount-targets --file-system-id <fs-id> --region <region>

    • EFS: aws efs describe-mount-targets --file-system-id <fs-id> --region <region>

  • Verify subnet routing: Ensure your subnets have proper routing (local VPC route for the CIDR range)

I get "Permission Denied" when writing to my mounted filesystem

When this occurs: Agent invocation succeeds and the agent can read files from the mount, but writing fails with "Permission denied"

Why this happens: Either the IAM role is missing write permissions, or the POSIX permissions on the directory set during access point creation don’t allow writes for the agent’s user.

Solution:

  • Check IAM permissions: Ensure your execution role includes s3files:ClientWrite (S3 Files) or elasticfilesystem:ClientWrite (EFS). Without write permissions, the mount is read-only. For more information, see permissions for Amazon Bedrock AgentCore Runtime execution role.

  • Check POSIX permissions: If the directory is owned by a different user than your container process, writes will be denied. Either:

    • Set your access point’s posixUser to match the uid/gid your container runs as, so all operations are performed as that user.

    • Set directory permissions to 777 to allow all users to write.

My container fails to start with HTTP 424 error on high-layer images

When this occurs: Your InvokeAgentRuntime calls return HTTP 424 (Failed Dependency) and your agent logs show Failed to mount overlay: No such file or directory. This occurs when your container image has more than 53 layers AND uses a non-numeric USER directive (e.g., USER myuser instead of USER 1000).

Why this happens: Container images with many layers combined with non-numeric USER directives can cause initialization failures.

Solution: Use one of these workarounds:

  • Use a numeric USER directive: In your Dockerfile, replace USER myuser with the numeric UID (e.g., USER 1000). You can find your user’s UID by running id myuser inside the container. This avoids the filesystem mount entirely.

  • Reduce image layers: Use multi-stage Docker builds to reduce your image to fewer than 53 layers. You can check your image’s layer count with:

docker inspect <image> | jq '.[0].RootFS.Layers | length'
  • Squash layers: Use docker build --squash or a tool like docker-squash to flatten your image layers.

The container image needs more build disk than this runtime has

When this occurs: After you create or update an agent runtime on platform version V2, AgentCore Runtime sets the agent runtime status to CREATE_FAILED or UPDATE_FAILED and reports this failure reason.

Why this happens: The build disk must hold both the compressed and the uncompressed container image. The build disk size is determined by the minimumMemoryInMiB in your resource configuration. If your image does not fit, the build fails before your agent starts.

Solution:

  1. Check the compressed size of your container image in Amazon ECR.

  2. Set a resource configuration with the recommended minimumMemoryInMiB for that size, or reduce your container image size.

The following table shows the recommended minimumMemoryInMiB value for each compressed image size.

Container image size (compressed) Recommended minimumMemoryInMiB

Up to 2 GB

1024 or higher

2–4 GB

4096 or higher

4–10 GB

8192

ServiceQuotaExceededException: maxImageSizeMb limit exceeded

When this occurs: CreateAgentRuntime or UpdateAgentRuntime returns a ServiceQuotaExceededException with the message maxImageSizeMb limit exceeded.

Why this happens: Your compressed container image is larger than the maximum image size for the platform version: 2 GB on platform version V1, and 10 GB on platform version V2.

Solution:

  1. Reduce your container image size so that the compressed image is below the limit for your platform version, and the compressed and uncompressed images together fit on the build disk.

  2. To use an image larger than 2 GB, set platformVersion to V2 and set a resource configuration in your CreateAgentRuntime or UpdateAgentRuntime request.

My agent runtime is in CREATE_FAILED or UPDATE_FAILED because of a lifecycle hook

When this occurs: After you create or update a V2 runtime that has a build warmup lifecycle hook, the runtime enters CREATE_FAILED or UPDATE_FAILED, and GetAgentRuntime returns one of the following failureReason values:

A lifecycle hook failed. Check your runtime's logs for which hook failed and why. For troubleshooting, see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-troubleshooting.html
A lifecycle hook didn't finish within its timeoutSeconds. Check your runtime's logs for which hook timed out. For troubleshooting, see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-troubleshooting.html

Why this happens: A warmup call returned a status code other than 2xx, AgentCore Runtime couldn’t connect to the hook, or the memory and disk calls didn’t finish within the 120 seconds that they share. In the second message, timeoutSeconds refers to this 120-second warmup time limit, which you can’t change. For more information, see Build warmup hook.

Find the failed call: Open your runtime’s log group, /aws/bedrock-agentcore/runtimes/<agentRuntimeId>-DEFAULT, and look in the log streams whose names start with build-logs-. Each warmup line starts with [LIFECYCLE-HOOK <epoch-milliseconds>], followed by [LIFECYCLE] for progress or [ERROR] for failures. A line can appear more than once for one create or update. For example:

[LIFECYCLE-HOOK 1718030400000] [LIFECYCLE] warmup hook (memory) started with 120.0 s of the 120 s warmup budget left

The following table describes the lines. The examples below leave out the [LIFECYCLE-HOOK <epoch-milliseconds>] prefix.

Line Example What it means

started

[LIFECYCLE] warmup hook (memory) started with 120.0 s of the 120 s warmup budget left

AgentCore Runtime sent the call. The line shows the time left for this call and any call after it.

succeeded

[LIFECYCLE] warmup hook (memory) succeeded in 50.0 s (70.0 s of the 120 s warmup budget left)

Your handler returned 2xx. The line shows how long the call took and the time left for the disk call.

timed out

[ERROR] warmup hook (disk) timed out after 70.0 s (memory used 50.0 s and disk 70.0 s of the 120 s warmup budget)

The two calls didn’t finish within 120 seconds. The line shows how much of the time each call used.

failed, with a status code

[ERROR] warmup hook (memory) failed: POST /warmup on port 8080 returned 500 after 3.2 s

Your handler returned a status code other than 2xx.

failed, with a connection error

[ERROR] warmup hook (memory) failed: POST /warmup on port 8080: connection refused

AgentCore Runtime couldn’t connect to the hook. The text after the colon is the connection error.

stopped

[LIFECYCLE] warmup hook (memory) stopped after 3.2 s: the runtime is shutting down

AgentCore Runtime stopped the call because the runtime is shutting down.

Solution: Fix the cause that the log lines show, then update the runtime again:

  • Make both calls fit in 120 seconds. If a call timed out, use the split in the timed out line to see which call used the time. Move expensive work to the memory call, and keep the disk call to the files that one session reads when it starts.

  • Return 2xx. If a call failed with a status code, check your application logs for the error in your warmup handler. Return 2xx only after the work succeeds.

  • Listen on the hook port before /ping passes. If a call failed with a connection error, make sure that a server listens on 0.0.0.0 at the hook port, and that it’s listening by the time your agent passes /ping. If the hook uses a port other than your serving port, start that server before /ping reports healthy. Check that the hook’s path and port in GetAgentRuntime match your server.

  • Keep /ping responsive. Don’t block your server’s only thread in the warmup handler. Run the warmup work in a separate thread or process so that your server keeps answering /ping.

My capacity provider is in state CREATE_FAILED

When this occurs: After you call CreateCapacityProvider for the Instances compute type, the capacity provider does not reach ACTIVE and instead enters CREATE_FAILED.

Why this happens: A capacity provider relies on multiple resources (such as a launch template and an Auto Scaling group) that the capacity provider operator role must be able to create. Missing permissions on that role lead to a creation failure.

Solution: Call the GetCapacityProvider API to retrieve the failure reason in the statusReason field. The statusReason identifies the resources that failed to create. Grant the capacity provider operator role the permissions it needs to create those resources, and then create the capacity provider again. For more information about the operator role, see Security model and permissions for Runtime Instances.

My agents on Instances do not have access to their credentials

When this occurs: An agent running on an Instances session cannot obtain the credentials it needs to call AWS services.

Why this happens: The runtime execution role is missing or cannot be assumed by AgentCore.

Solution: Make sure the execution role you configured for your runtime exists and allows bedrock-agentcore.amazonaws.com to call sts:AssumeRole. For more information, see permissions for Amazon Bedrock AgentCore Runtime execution role.

Best practices

Enable comprehensive logging

Implement thorough logging in your agent:

  • Include request/response logging in your agent

  • Log critical paths and error conditions

Use structured error handling

Implement clear error reporting:

  • Return clear error messages with specific codes

  • Include actionable information in error responses

Test incremental changes

Follow a methodical testing approach:

  • When modifying your agent, test locally before deployment

  • Validate payload compatibility with both local and deployed environments

Monitor performance

Set up monitoring for your agent:

  • Use CloudWatch metrics to track invocation patterns

  • Set up alarms for error rates and latency