Debugging your gateway

While your gateway is in development, you can turn on debugging to return details on target configuration issues, including lambda function errors, egress authorizer errors, target specification parameter validation errors.

To turn on debugging, you set the exceptionLevel value as DEBUG when you make a CreateGateway or UpdateGateway request.

When you're done debugging your gateway, you can update the gateway and remove the exceptionLevel field, such that the message to the end user only shows an unspecified internal error.

Example

As an example, if debugging is turned on for a gateway, you might submit the following request payload to call a tool using a Lambda function:

{
   'jsonrpc': '2.0', 
   'id': 24, 
   'method': 'tools/call', 
   'params': {
    'name': 'LambdaTarget___get_order_tool', 
    'arguments': {
      'orderId': 'ORD-12345-67890', 
      'customerId': 'CUST-98765' 
    }
  }
}

If the user doesn't have permissions to invoke the Lambda function, the debugging message would be returned in the _meta field within the result of the response, as in the following example:

{
  "jsonrpc": "2.0",
  "id": 24,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Access denied while invoking Lambda function arn:aws:lambda:us-west-2:123456789012:function:TestGatewayLambda. Check the permissions on the Lambda function and Gateway execution role, and retry the request."
      }
    ],
    "_meta": {
      "debug": {
        "type": "text",
        "text": "Access denied while invoking Lambda function arn:aws:lambda:us-west-2:123456789012:function:TestGatewayLambda. Check the permissions on the Lambda function and Gateway execution role, and retry the request."
      }
    },
    "isError": true
  }
}

If debugging is turned off, a generic error message would be returned in the text field of the content field within the result of the response, as in the following example:

{
  "jsonrpc": "2.0",
  "id": 24,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "An internal error occurred. Please retry later."
      }
    ],
    "isError": true
  }
}

Debugging ListTools

curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": "list-tools-request",
    "method": "tools/list"
  }'
        

Debugging CallTool

curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": "call-tool-request", 
    "method": "tools/call",
    "params": {
      "name": "getWeather",
      "arguments": {
        "location": "Seattle, WA"
      }
    }
  }'
        

Debugging SearchTools

curl -X POST https://gateway-id.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": "search-tools-request",
    "method": "tools/call", 
    "params": {
      "name": "x_amz_bedrock_agentcore_search",
      "arguments": {
        "query": "How do I process images?"
      }
    }
  }'