Versions

Examples built with AgentCore CLI @aws/agentcore@0.26.0. Commands or flags may differ in other versions. Run agentcore --version to check yours.

Troubleshooting

Common issues and solutions when building agents on AgentCore.

---

Local Development (agentcore dev)

Symptom	Root Cause	Solution
error starting dev server: terminal	IDE terminal can't allocate TTY	Use agentcore dev --logs or run in a native terminal window
.venv not found / module import errors	Python deps not installed	Run cd app/<Name> && uv venv && uv sync
Port 8080 already in use	Another process on the port	Kill it, or use agentcore dev --port 8081
Payload shows "unknown" or garbled JSON	CLI wraps input in {"prompt":"..."}	Add payload unwrapping logic (see below)
ModuleNotFoundError: bedrock_agentcore	Package not in venv	Run uv add bedrock-agentcore then uv sync
Hot reload not working	File outside watched directory	Ensure changes are inside app/<Name>/

Payload Unwrapping

When you send a prompt with agentcore dev "<json>", the CLI wraps your JSON inside {"prompt": "<your json as string>"}. If your agent expects structured event payloads, unwrap it:

import json

def unwrap_payload(payload: dict) -> dict:
    """Unwrap nested JSON from agentcore dev's prompt wrapper."""
    if "prompt" in payload:
        prompt_value = payload["prompt"]
        if isinstance(prompt_value, str):
            try:
                parsed = json.loads(prompt_value)
                if isinstance(parsed, dict):
                    return parsed
            except (json.JSONDecodeError, TypeError):
                pass
    return payload

---

Memory

Symptom	Root Cause	Solution
ResourceNotFoundException: Memory not found	Memory not deployed yet	Deploy first (agentcore deploy), then test locally
Agent doesn't remember across sessions	Memory mode is shortTerm only	Use longAndShortTerm with SEMANTIC strategy
Memory stuck in CREATING status	IAM permissions or KMS issue	Check execution role permissions; use agentcore status
Different users seeing each other's memories	actor_id hardcoded	Use unique actor_id per user (from context or JWT)
Extraction jobs failing	Strategy misconfigured	Check CloudWatch logs for the memory resource

Graceful Degradation Pattern

Memory is unavailable during local dev. Always wrap memory initialization in try/except:

session_manager = None
try:
    session_manager = get_memory_session_manager(session_id, actor_id)
except Exception as exc:
    log.warning("Memory unavailable: %s", exc)

# Agent works fine with session_manager=None
agent = Agent(model=model, session_manager=session_manager, tools=tools)

---

Gateway

Symptom	Root Cause	Solution
Gateway stuck in CREATING	IAM trust policy missing	Service role must trust bedrock-agentcore.amazonaws.com
Target stuck in SYNCHRONIZING	MCP server version incompatible	Confirm the target's MCP server supports a protocol version Gateway currently accepts; upgrade the Gateway's supportedVersions via UpdateGateway if needed
AccessDeniedException on tool call	Missing Lambda invoke permission	Add lambda:InvokeFunction to gateway service role
Agent can't find the tool	Target not READY, or schema invalid	Check agentcore status; verify JSON schema is valid
Tool returns unexpected format	Lambda using HTTP envelope	Return direct objects, not {statusCode, body} wrappers
$ref or $defs in tool schema	Schemas must be self-contained	Inline all references; no JSON Schema $ref allowed

---

Deployment

Symptom	Root Cause	Solution
runtimeVersion PYTHON_3_14 warnings	CLI scaffolded pre-release Python	Change to PYTHON_3_13 in agentcore.json
Deploy fails with IAM error	Execution role not configured	Check agentcore.json or let CLI create role automatically
Deploy takes very long (>10 min)	Memory or Gateway provisioning	Memory STM: ~60s, LTM: ~180s. Gateway: ~60s. Normal.
CREATE_FAILED on runtime	Code error or missing entrypoint	Check failureReason via agentcore status
exec format error in container deploy	Docker image not ARM64	Build with --platform linux/arm64

---

Cedar Policies

Symptom	Root Cause	Solution
Policy deploy fails	Bare resource without type	Use resource is AgentCore::Gateway (any action) or resource == AgentCore::Gateway::"<arn>" (specific actions)
Policy has no effect	Mode is LOG_ONLY	Switch to ENFORCE after validating in logs
ValidationException on create	Schema mismatch with Gateway tools	Deploy Gateway first so tool schemas are available for validation
Numeric comparison fails	Using operators on Decimal type	Use "type": "integer" in tool schema for direct < > ops
Specific action + type constraint fails	Using resource is with action ==	When specifying specific actions, you must use the full Gateway ARN: resource == AgentCore::Gateway::"<arn>"

Cedar Syntax Quick Reference

// Allow ALL tools on a gateway (type constraint OK here — no specific action)
permit(
  principal,
  action,
  resource is AgentCore::Gateway
);

// Allow a specific tool (MUST use Gateway ARN)
permit(
  principal,
  action == AgentCore::Action::"TargetName___tool_name",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway"
);

// Allow a specific tool only when condition is met (MUST use Gateway ARN)
permit(
  principal,
  action == AgentCore::Action::"TargetName___tool_name",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway"
)
when {
  context.input.priority == "HIGH"
};

---

Authentication / Identity

Symptom	Root Cause	Solution
AccessDeniedException invoking agent	Missing IAM permissions	Caller needs bedrock-agentcore:InvokeAgentRuntime
JWT validation fails	Discovery URL or client mismatch	Verify --discovery-url and --allowed-clients match IdP
Credential provider not found	Name mismatch or wrong region	Names are case-sensitive and region-scoped
OAuth callback fails	Callback URL not registered	Register the callbackUrl from provider creation response

---

General

Symptom	Root Cause	Solution
Unknown service in boto3	boto3 too old	pip install --upgrade boto3 botocore
CLI command not recognized	Outdated CLI version	npm install -g @aws/agentcore@0.26.0 — before upgrading, check the CLI releases page for compatibility notes
Session terminated early	Idle timeout too short	Increase via agentcore.json or agentcore add agent
504 Gateway Timeout on invoke	Agent took too long	Check agent logs; optimize tool calls or model

---

---

Region and Service Availability

Symptom	Root Cause	Solution
UnknownServiceException or Could not connect to the endpoint URL	AgentCore not available in the selected region	Check which regions support AgentCore in the Amazon Bedrock AgentCore Developer Guide. Switch your target region in agentcore/aws-targets.json.
Deploy succeeds but runtime endpoint returns 503	Service capacity or rollout lag in a new region	Wait a few minutes and retry. If the issue persists, open a support case.

---

IAM Access Errors

AgentCore uses two distinct IAM roles. Errors often come from confusing which role is missing a permission.

Role	When it is used	Common missing permissions
Deployment role (your caller identity)	Running agentcore deploy, agentcore add, agentcore destroy	bedrock-agentcore:CreateAgentRuntime, iam:PassRole, ecr:*, cloudformation:*
Execution role (attached to the runtime)	Agent code running inside AgentCore	bedrock:InvokeModel, bedrock-agentcore:GetMemory, Lambda invoke, secrets access

If you see AccessDeniedException during deploy, the deployment role is missing permissions. If you see it inside agent code at runtime, the execution role is missing permissions. Check CloudWatch logs to distinguish the two.

---

Model Access Errors

Symptom	Root Cause	Solution
AccessDeniedException: You don't have access to the model	Bedrock model not enabled in your account	Open the Bedrock console and request access under Model access for the specific model and region.
ValidationException: The provided model identifier is invalid	Model ID mismatch or model not available in the region	Verify the exact model ID in the Bedrock console for your target region.

---

Deployment Rollback

If a deploy fails partway through or introduces a regression, you can return to the previous working state:

1. Run agentcore status to identify which resources are in a failed or updating state.
2. For CloudFormation-backed resources, open the AWS CloudFormation console and choose Roll back on the failed stack, or run agentcore destroy to tear down and re-deploy from a known-good agentcore.json.
3. To redeploy the previous configuration, restore agentcore.json from version control and run agentcore deploy again.
4. If a runtime is stuck in UPDATE_FAILED, delete it manually in the AgentCore console or via CLI, then redeploy.

---

Cleanup Failures

Running agentcore destroy removes the CDK stack, but some resources may persist if deletion fails or if they were created outside the managed stack.

Resource	Why it may persist	How to verify removal
ECR repositories	Non-empty repositories are not deleted by default	Check the ECR console; delete images then delete the repository manually
Secrets Manager secrets	Secrets have a minimum 7-day recovery window	Look for secrets named after your project in the Secrets Manager console; use Force delete if needed
CloudWatch log groups	Log groups are retained by default	Search for /aws/agentcore/ prefixed groups in the CloudWatch console and delete manually
IAM roles	Roles with attached policies may block deletion	Check IAM for roles prefixed with your project name; detach policies and delete

After running agentcore destroy, verify cleanup with:

agentcore status

A clean teardown shows no resources in the output.

---

Safe Log Inspection

Before sharing logs or pasting them into support channels:

• Redact AWS account IDs, ARNs, and region identifiers if your account details are sensitive.
• Remove any bearer tokens, API keys, or client secrets that may appear in request headers logged at DEBUG level.
• Avoid pasting full agentcore.json contents if they reference internal endpoint URLs or secret names that reveal infrastructure details.

To inspect logs without exposing sensitive data in your terminal history, pipe output to a file first:

agentcore logs --runtime MyAgent > /tmp/agent-logs.txt
# Then redact before sharing

Getting Help

• AgentCore Developer Guide
• Strands SDK Documentation
• AgentCore Samples
• Run agentcore --help for the latest command reference