Debugging Basics

Six examples to get you comfortable reading AWS SDK errors - four basic and two intermediate.

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3). By the end you can pull the error code, the request id, and enough context to know which playbook in this section to reach for.

Prerequisites

• Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-dynamodb (Node.js 18+; install the client for whichever service you use).
• Credentials configured via aws configure, environment variables, or an IAM role.
• Basic familiarity with the exception a failed call raises in each SDK - ClientError in boto3, a typed service exception in SDK v3.

Basic Examples

1. Catch the Error and Print the Code

The first move in any AWS SDK debugging session is separating the error code from the message.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    ddb.get_item(TableName="orders", Key={"id": {"S": "123"}})
except ClientError as err:
    code = err.response["Error"]["Code"]
    message = err.response["Error"]["Message"]
    print(f"code={code} message={message}")

// --- TypeScript (AWS SDK v3) ---
import { GetItemCommand } from "@aws-sdk/client-dynamodb";
 
try {
  await ddb.send(new GetItemCommand({ TableName: "orders", Key: { id: { S: "123" } } }));
} catch (err) {
  const e = err as { name?: string; message?: string };
  console.log(`code=${e.name} message=${e.message}`);
}

• boto3 raises ClientError for every service-side failure; the code lives at err.response["Error"]["Code"].
• SDK v3 raises a typed exception whose class name and .name property both carry the error code.
• The message is for humans; the code is what your code should branch on.
• Never silently swallow an exception without at least logging the code.

Related: Categories of AWS SDK Failures - which bucket a code falls into.

2. Pull the Request Id

Every AWS API response carries a request id, and it is the single most useful thing to log for support and tracing.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    ddb.get_item(TableName="orders", Key={"id": {"S": "123"}})
except ClientError as err:
    request_id = err.response["ResponseMetadata"]["RequestId"]
    print(f"request_id={request_id}")

// --- TypeScript (AWS SDK v3) ---
import { GetItemCommand } from "@aws-sdk/client-dynamodb";
 
try {
  await ddb.send(new GetItemCommand({ TableName: "orders", Key: { id: { S: "123" } } }));
} catch (err) {
  const e = err as { $metadata?: { requestId?: string } };
  console.log(`request_id=${e.$metadata?.requestId}`);
}

• boto3 nests it under ResponseMetadata.RequestId on the ClientError.
• SDK v3 nests it under $metadata.requestId on the thrown exception.
• Successful responses carry the same field - log it there too, not only on failure.
• AWS Support and CloudWatch Logs Insights queries key off this id, so log it structured, not buried in free text.

3. Distinguish a Client Error from a Server Error

The HTTP status code tells you whether the problem is your request or AWS's side.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    ddb.get_item(TableName="orders", Key={"id": {"S": "123"}})
except ClientError as err:
    status = err.response["ResponseMetadata"]["HTTPStatusCode"]
    if 400 <= status < 500:
        print("client-side: fix the request")
    else:
        print("server-side: likely transient, safe to retry")

// --- TypeScript (AWS SDK v3) ---
import { GetItemCommand } from "@aws-sdk/client-dynamodb";
 
try {
  await ddb.send(new GetItemCommand({ TableName: "orders", Key: { id: { S: "123" } } }));
} catch (err) {
  const status = (err as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode ?? 0;
  if (status >= 400 && status < 500) {
    console.log("client-side: fix the request");
  } else {
    console.log("server-side: likely transient, safe to retry");
  }
}

• 4xx almost always means fix the request - bad input, missing permission, wrong resource name.
• 5xx usually means a transient service-side condition, which the SDK's retry logic already handles for most calls.
• ThrottlingException is technically a 4xx but behaves like a transient error - it is retryable, unlike most 4xxs.
• Status code plus error code together narrow the failure bucket fast.

4. Check Whether the SDK Marked It Retryable

Both SDKs know, per error, whether a retry is likely to help.

# --- Python (boto3) ---
from botocore.exceptions import ClientError
 
try:
    ddb.get_item(TableName="orders", Key={"id": {"S": "123"}})
except ClientError as err:
    retryable_codes = {"ThrottlingException", "ProvisionedThroughputExceededException"}
    code = err.response["Error"]["Code"]
    print("retryable" if code in retryable_codes else "not retryable")

// --- TypeScript (AWS SDK v3) ---
import { GetItemCommand } from "@aws-sdk/client-dynamodb";
 
try {
  await ddb.send(new GetItemCommand({ TableName: "orders", Key: { id: { S: "123" } } }));
} catch (err) {
  const e = err as { $retryable?: { throttling?: boolean } };
  console.log(e.$retryable ? "retryable" : "not retryable");
}

• boto3 does not expose a first-class retryable flag on the exception; you check the code against known throttling/transient codes, or trust that the built-in retry strategy already tried and gave up.
• SDK v3 attaches a $retryable hint to some errors, including a throttling flag.
• If an error reaches your catch/except block at all, the SDK's own retry budget has already been exhausted for that call.
• Do not build a second retry loop on top of an error the SDK already gave up on without understanding why it stopped.

Intermediate Examples

5. Correlate a Client Error with CloudWatch Logs

The request id from your SDK error is the same request id that appears in the service's own CloudWatch Logs, if the service logs per-request.

# --- Python (boto3) ---
import boto3
from botocore.exceptions import ClientError
 
logs = boto3.client("logs")
 
try:
    ddb.get_item(TableName="orders", Key={"id": {"S": "123"}})
except ClientError as err:
    request_id = err.response["ResponseMetadata"]["RequestId"]
    # Search the relevant log group for this request id to find server-side context.
    logs.filter_log_events(logGroupName="/aws/lambda/orders-handler", filterPattern=request_id)

// --- TypeScript (AWS SDK v3) ---
import { CloudWatchLogsClient, FilterLogEventsCommand } from "@aws-sdk/client-cloudwatch-logs";
 
const logsClient = new CloudWatchLogsClient({});
 
try {
  await ddb.send(new GetItemCommand({ TableName: "orders", Key: { id: { S: "123" } } }));
} catch (err) {
  const requestId = (err as { $metadata?: { requestId?: string } }).$metadata?.requestId;
  await logsClient.send(
    new FilterLogEventsCommand({ logGroupName: "/aws/lambda/orders-handler", filterPattern: requestId }),
  );
}

• Treat the request id as a join key across your application logs, AWS SDK logs, and the service's own CloudWatch Logs.
• This is far faster than guessing at timing to line up a client-side error with server-side context.
• Not every service emits per-request logs to CloudWatch by default - check the service's logging docs.
• Structure your own application logs to always include the request id field so it is searchable later.

6. Enable SDK-Level Debug Logging

When the error itself is not enough, both SDKs can log the raw wire traffic.

# --- Python (boto3) ---
import logging
import boto3
 
boto3.set_stream_logger("botocore", level=logging.DEBUG)
# Now every request/response, including headers and retry attempts, is logged.
ddb = boto3.client("dynamodb")

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 
const ddb = new DynamoDBClient({
  logger: console, // logs each request/response lifecycle event to the console
});

• botocore debug logging is extremely verbose - enable it only while reproducing an issue, never in steady-state production.
• SDK v3's logger option accepts any object with debug/info/warn/error methods, so you can route it to your existing logger.
• Debug logs show retry attempts, which is the fastest way to confirm whether the SDK retried at all before the error surfaced.
• Turn this off again once you have what you need - it adds real overhead and can leak request bodies into logs.

FAQs

Related

• Categories of AWS SDK Failures - the buckets these error codes sort into.
• Throttling & Rate-Limit Defect Walkthrough - a full walkthrough once you spot throttling.
• Production Incident Response for AWS-Backed Services - what to do once you can read the error fast.
• Debugging & Incident Response Best Practices - the habits to bake in permanently.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+). 49454e4f4d5f434e4f5904434556494d43451b1b191e56181a181c1a1d