AWS CLI v2 のエラー出力が構造化されています

ウィスキー、シガー、パイプをこよなく愛する大栗です。

AWS CLI v2 のバージョン 2.34.0 で、エラー出力を構造化して表示する機能と、標準出力を抑制する off 形式が追加されましたのでご紹介します。

• Announcing new output formats in AWS CLI v2
• Structured error output in the AWS CLI
• Setting the output format in the AWS CLI

構造化エラー出力

AWS CLI でエラーが発生した場合、従来はエラーコードとメッセージのみが表示されていました。しかし、AWS サービスの API が返すエラーには、バケット名やリソース ID、バリデーションの理由など、デバッグに役立つ追加情報が含まれていることがあります。これらの情報を確認するには --debug オプションを使用する必要がありました。

バージョン 2.34.0 からは、これらの追加詳細が標準エラー出力（stderr）に直接表示されるようになりました。さらに、新しい --cli-error-format オプションにより、エラーの出力形式を選択できるようになっています。

エラー出力形式

サポートされるエラー出力形式は以下の6種類です。

設定方法

エラー出力形式は以下の3つの方法で設定できます。

CLI フラグ

$ aws <command> --cli-error-format json

設定ファイル（~/.aws/config）

[default]
cli_error_format = json

環境変数

$ export AWS_CLI_ERROR_FORMAT=yaml

アクセシビリティの改善

2025年9月から、一部の例外で aws: [ERROR]: プレフィックスが追加されていましたが、今回のリリースで enhanced および legacy 形式の全てのエラーにおいてプレフィックスが統一されました。これにより、エラーの発生をプログラムから検知しやすくなっています。

出力オフ形式（off format）

AWS CLI のコマンド出力を非表示にしたい場合があります。例えば、AWS Secrets Manager でシークレットを作成する際に、シークレットの ARN やバージョン情報がログに残ることを避けたいケースです。

新しい off 形式は標準出力（stdout）を抑制しつつ、標準エラー出力（stderr）のエラーは維持します。コマンドの成否は終了コード（$?）で確認できます。

設定方法

出力オフ形式も構造化エラー出力と同様に 3 つの方法で設定できます。

今回のアップデートで何が増えたか

今回のアップデートで追加された内容を整理します。

新しいオプション: --cli-error-format

バージョン 2.34.0 より前の AWS CLI では、エラー出力の形式を制御するオプションは存在しませんでした。エラーが発生すると、常に以下のような固定形式でエラーコードとメッセージのみが表示されていました。

実際にバージョン 2.33.30 で存在しない S3 バケットにアクセスした場合の出力は以下の通りです。

~ $ aws --version
aws-cli/2.33.30 Python/3.13.11 Linux/6.1.161-183.298.amzn2023.x86_64 exec-env/CloudShell exe/x86_64.amzn.2023

~ $ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt

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

エラーコードの NoSuchBucket とメッセージのみが表示されています。このとき、S3 の API は BucketName などの追加情報をレスポンスに含めていますが、それらは表示されず、確認するには --debug オプションで大量のデバッグログを出力する必要がありました。また aws: [ERROR]: プレフィックスも付与されていません。

今回、新たに --cli-error-format オプションが追加され、6種類の形式からエラーの表示方法を選択できるようになりました。デフォルトの enhanced 形式では、追加のエラー詳細が自動的に表示されます。

新しい出力形式: --output off

従来の --output オプションで指定できる形式は json、yaml、yaml-stream、text、table の5種類でした。今回、新たに off 形式が追加され、標準出力を抑制できるようになりました。

やってみる

実際にバージョン 2.34.0 以上の AWS CLI で各機能を試してみます。

構造化エラー出力を全形式で試す

存在しない S3 バケットに対してオブジェクトの取得を実行し、全6形式の違いを確認します。

enhanced 形式（デフォルト）

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

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

デフォルトの enhanced 形式では、従来のエラーメッセージに加えて Additional error details として BucketName が表示されています。これが今回のアップデートの変化です。従来は --debug で膨大なログの中から探す必要があった情報が、すぐに確認できるようになりました。enhanced 形式以外では Additional error details は BucketName と同じ階層であり YAML ではない表記なので少々奇妙です。

json 形式

$ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt \
    --cli-error-format json
{
    "Code": "NoSuchBucket",
    "Message": "The specified bucket does not exist",
    "BucketName": "amzn-s3-demo-bucket"
}

JSON 形式では Code、Message、および追加フィールドが構造化されて出力されます。スクリプトやパイプラインで jq などと組み合わせてエラー処理を行うのに適しています。

yaml 形式

$ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt \
    --cli-error-format yaml
BucketName: amzn-s3-demo-bucket
Code: NoSuchBucket
Message: The specified bucket does not exist

YAML 形式も json 形式と同様に全フィールドが構造化されて出力されます。

text 形式

$ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt \
    --cli-error-format text
amzn-s3-demo-bucket	NoSuchBucket	The specified bucket does not exist

text 形式ではタブ区切りで全フィールドが出力されます。Shell や grep、awk などでテキスト処理を行いのに適しています。

table 形式

$ aws s3api get-object \
    --bucket amzn-s3-demo-bucket \
    --key file.txt out.txt \
    --cli-error-format table
--------------------------------------------------------------------------------
|                                     error                                    |
+----------------------+---------------+---------------------------------------+
|      BucketName      |     Code      |                Message                |
+----------------------+---------------+---------------------------------------+
|  amzn-s3-demo-bucket |  NoSuchBucket |  The specified bucket does not exist  |
+----------------------+---------------+---------------------------------------+

table 形式では ASCII テーブルとして整形されます。ターミナル上で視覚的にエラー内容を確認したい場合に便利です。

legacy 形式

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

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

legacy 形式ではバージョン 2.34.0 より前と同様に、エラーコードとメッセージのみが表示されます。BucketName などの追加詳細は含まれません。既存のスクリプトでエラーメッセージのパースを行っている場合には、この形式を指定することで後方互換性を維持できます。なお aws: [ERROR]: プレフィックスは legacy 形式でも付与されるようになっています。

出力オフ形式を試す

Secrets Manager でシークレットを作成する際に --output off を使用します。

$ aws secretsmanager create-secret \
    --name my-secret \
    --secret-string "password123" \
    --output off
$ echo $?
0

ARN、Name、VersionId が標準出力に表示されますが、コマンドの出力は一切表示されず、終了コード 0 で正常終了したことが確認できます。従来は > /dev/null にリダイレクトして出力を抑制していましたが、--output off であれば設定ファイルや環境変数でデフォルト設定にすることもでき、コマンドごとにリダイレクトを記述する必要がありません。また、Windows 環境では /dev/null が使用できないため、クロスプラットフォームでの利用にも適しています。

さいごに

AWS CLI のエラー出力は、従来はエラーコードとメッセージのみの固定形式でした。追加のエラー詳細を確認するには --debug で大量のログを出力するしかなく、デバッグ時に不便を感じることがありました。今回の構造化エラー出力により、デバッグに必要な情報をすぐに確認可能になりました。

json 形式や yaml 形式での出力はスクリプトからのエラーハンドリング自動化にも活用できますし、既存のスクリプトとの互換性が心配な場合は legacy 形式を指定できるため、安心してアップグレードできると思います。

また、出力オフ形式は地味ながらもセキュリティ面で重要な機能です。> /dev/null と違ってエラーは維持されるため、CI/CD パイプラインでの利用に適しています。

AWS CLI を日常的に使用されている方は、バージョン 2.34.0 へのアップグレードをお勧めします。