Troubleshoot AgentCore Browser

This section provides solutions to common issues you might encounter when using the Amazon Bedrock AgentCore Browser.

Permission denied errors

Symptom: Errors mentioning access denied or insufficient permissions.

Solution:

Model access denied

Symptom: Errors about model access or authorization when running agents.

Solution:

Browser session timeout

Symptom: Browser sessions end unexpectedly or timeout errors occur.

Solution:

Recording not appearing in Amazon S3

Symptom: No recording files in your Amazon S3 bucket after session completes.

Solution:

Playwright connection errors

Symptom: Cannot connect to browser with Playwright or WebSocket errors.

Solution:

Agent cannot make progress due to CAPTCHA checks

Issue: Your agent gets blocked by CAPTCHA verification when using the Browser tool to interact with websites.

Cause: Anti-bot measures on popular websites detect automated browsing and require human verification.

Solution: Structure your agent to avoid search engines and implement the following architecture pattern:

CORS errors when integrating with browser applications

Issue: Cross-Origin Resource Sharing (CORS) errors occur when building browser-based web applications that call a custom Amazon Bedrock AgentCore runtime server.

Cause: Browser security policies block cross-origin requests to your runtime server during local development or self-hosted deployment.

Solution: Add CORS middleware to your BedrockAgentCoreApp to handle cross-origin requests from your frontend:

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from fastapi.middleware.cors import CORSMiddleware

app = BedrockAgentCoreApp()

# Add CORS middleware to allow browser requests
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],           # Customize in production
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Handle browser preflight requests to /invocations
@app.options("/invocations")
async def options_handler():
    return {"message": "OK"}

@app.entrypoint
def my_agent(payload):
    return {"response": "Hello from agent"}

Session Replay and Web Bot Auth don’t work in new browser windows or contexts

Issue: Session Replay and Web Bot Auth features are not available when your automation code creates new browser windows or contexts.

Cause: These features rely on browser extensions that only work in the default browser context provided by Amazon Bedrock AgentCore. When you create a new context using methods like browser.new_context() in Playwright, the extensions are not available.

Solution: Use the default browser context provided when you connect to the browser session. Avoid creating new contexts or windows if you need Session Replay or Web Bot Auth functionality.

# ✓ Use the existing default context
context = browser.contexts[0]
page = context.pages[0]

# ✗ Don't create new contexts - Session Replay and Web Bot Auth won't work
# context = browser.new_context()

Browser extensions issues

Extension download fails with access denied

Symptom: Session fails to start with errors related to Amazon S3 access when using extensions.

Solution:

Extension rejected due to invalid format

Symptom: Session fails to start with validation errors about the extension file format.

Solution:

Browser profile issues

Failed to save browser session profile due to concurrent operation on the profile

Symptom: SaveBrowserSessionProfile throws ConflictException.

Solution:

Failed to save browser session profile due to concurrent operation on the session

Symptom: SaveBrowserSessionProfile throws ConflictException.

Solution:

Authentication fails when loading a saved browser profile

Symptom: A browser session loaded from a saved profile requires re-authentication even though the profile was saved with valid authentication cookies.

Cause: Cookies stored in the browser profile have expired. Websites set expiration times on cookies (such as authentication tokens), and the browser automatically removes expired cookies according to these expiration dates. When you load a profile, any cookies that have expired since the profile was saved will not be available.

Solution:

Troubleshooting Root Certificate Authority issues

The following table describes common errors and their resolutions when configuring root CA certificates for Amazon Bedrock AgentCore Browser.

Troubleshooting browser proxies

Errors when starting a session with proxy

Symptom: StartBrowserSession returns an HTTP 400 error with a message beginning with Failed to set up browser proxy:.

Cause: The proxy configuration or credentials secret is invalid.

Solution:

Proxy connection errors in browser

Symptom: A browser session starts successfully, but page navigation fails for proxied domains with HTTP 502 errors or net::ERR_INVALID_AUTH_CREDENTIALS.

Cause: The browser cannot connect to the proxy server, or the proxy server rejects the provided credentials. These are Chromium network errors, not AWS API errors.

Solution:

Troubleshooting InvokeBrowser OS actions

The following table describes common errors when using the InvokeBrowser API for OS-level browser actions.

Solution: