Structured error output in the AWS CLI - AWS Command Line Interface
Configuring error formatError output formatsComplete example

Structured error output in the AWS CLI

This topic describes the structured error output formats for the AWS Command Line Interface (AWS CLI). The CLI writes errors to stderr and supports the following formats:

  • enhanced (default) – Error message with additional details displayed inline. Use for human-readable debugging.

  • json – The output is formatted as a JSON string with all error fields. Use for automation and scripting.

  • yaml – The output is formatted as a YAML string with all error fields. Use for automation and scripting.

  • text – Formats errors using the text formatter. Use for quick visual scanning.

  • table – Formats errors using the table formatter. Use for quick visual scanning.

  • legacy – Original error format without structured details. Use for backward compatibility.

Configuring error format

You can configure the error format using any of the following methods:

Command-line flag
$ aws <command> --cli-error-format json
Configuration file (~/.aws/config)
[default]
cli_error_format = json
Environment variable
$ export AWS_CLI_ERROR_FORMAT=yaml

Error output formats

The following sections describe each format:

Enhanced format (default)

The enhanced format displays error messages with additional details inline for simple values. For complex structures, the format provides a hint to use JSON or YAML.

Example: Missing region configuration

aws: [ERROR]: An error occurred (NoRegion): You must specify a region. You can also configure your region by running "aws configure".

Example: Nonexistent S3 bucket with additional fields


aws: [ERROR]: An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist

Additional error details:
BucketName: amzn-s3-demo-bucket

Example: Complex error fields


An error occurred (TransactionCanceledException) when calling the TransactWriteItems operation: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

Additional error details:
CancellationReasons: <complex value>
Use "--cli-error-format json" or another error format to see the full details.

JSON format

The JSON format provides a structured representation with all error fields.

Example: Missing region configuration

{
    "Code": "NoRegion",
    "Message": "You must specify a region. You can also configure your region by running \"aws configure\"."
}

Example: Nonexistent S3 bucket

{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}

YAML format

The YAML format provides a structured representation with all error fields.

Example: Missing region configuration

Code: NoRegion
Message: You must specify a region. You can also configure your region by running "aws configure".

Example: Nonexistent S3 bucket

Code: NoSuchBucket
Message: The specified bucket does not exist
BucketName: amzn-s3-demo-bucket

Text format

The text format uses the same formatter as successful command output.

Example: Nonexistent S3 bucket

amzn-s3-demo-bucket  NoSuchBucket    The specified bucket does not exist

Table format

The table format uses the same formatter as successful command output.

Example: Nonexistent S3 bucket

-------------------------------------------------------------------------------------|
|                                       error                                        |
+---------------------------+---------------+----------------------------------------+
|        BucketName         |     Code      |                Message                 |
+---------------------------+---------------+----------------------------------------+
|  amzn-s3-demo-bucket      |  NoSuchBucket |  The specified bucket does not exist   |
+---------------------------+---------------+----------------------------------------+

Legacy format

The legacy format provides the original error format without structured details. This format does not include the "An error occurred (ErrorCode):" prefix for CLI exceptions.

Example: Missing region configuration

aws: [ERROR]: You must specify a region. You can also configure your region by running "aws configure".

Example: Nonexistent S3 bucket

An error occurred (NoSuchBucket) when calling the GetObject operation: The specified bucket does not exist
Note

Errors now consistently include the aws: [ERROR]: prefix for CLI exceptions. Earlier versions did not always include this prefix.

The following exceptions always use the legacy format regardless of the configured error format:

  • UnknownArgumentError – Displays usage information

  • Keyboard interrupts (KeyboardInterrupt)

Complete example

The following example shows a command with JSON error formatting:

$ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt \
    --cli-error-format json

Output (stderr):

{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}

The BucketName field is a modeled error member returned by the Amazon S3 service.