Salida de error estructurado en la AWS CLI - AWS Command Line Interface
Configuración del formato de errorFormatos de salida de errorEjemplo completo

Salida de error estructurado en la AWS CLI

Este tema describe los formatos de salida de error estructurado para la AWS Command Line Interface (AWS CLI). La CLI escribe los errores en stderr y admite los siguientes formatos:

  • enhanced (predeterminado): mensaje de error con detalles adicionales que se muestran en línea. Se utiliza para la depuración legible por el usuario.

  • json: la salida se formatea como una cadena JSON con todos los campos de error. Se usa para la automatización y el scripting.

  • yaml: la salida se formatea como una cadena YAML con todos los campos de error. Se usa para la automatización y el scripting.

  • text: formatea los errores usando el formateador de texto. Se utiliza para el escaneo visual rápido.

  • table: formatea los errores usando el formateador de tabla. Se utiliza para el escaneo visual rápido.

  • legacy: formato de error original sin detalles estructurados. Se usa para la retrocompatibilidad.

Configuración del formato de error

Puede configurar el formato de error utilizando cualquiera de los siguientes métodos:

Indicador de línea de comandos
$ aws <command> --cli-error-format json
Archivo de configuración: (~/.aws/config)
[default]
cli_error_format = json
Variable de entorno
$ export AWS_CLI_ERROR_FORMAT=yaml

Formatos de salida de error

En las secciones siguientes se describe cada formato:

Formato mejorado (predeterminado)

El formato mejorado muestra los mensajes de error con detalles adicionales en línea para valores simples. Para estructuras complejas, el formato proporciona una sugerencia para usar JSON o YAML.

Ejemplo: Ausencia de configuración de la región

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

Ejemplo: Bucket de S3 inexistente con campos adicionales


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

Ejemplo: Campos de error complejos


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.

Formato JSON

El formato JSON proporciona una representación estructurada con todos los campos de error.

Ejemplo: Ausencia de configuración de la región

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

Ejemplo: Bucket de S3 inexistente

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

Formato YAML

El formato YAML proporciona una representación estructurada con todos los campos de error.

Ejemplo: Ausencia de configuración de la región

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

Ejemplo: Bucket de S3 inexistente

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

Formato de texto

El formato de texto utiliza el mismo formateador que la salida del comando que se ha ejecutado correctamente.

Ejemplo: Bucket de S3 inexistente

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

Formato de tabla

El formato de tabla utiliza el mismo formateador que la salida del comando que se ha ejecutado correctamente.

Ejemplo: Bucket de S3 inexistente

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

Formato heredado

El formato heredado proporciona el formato de error original sin detalles estructurados. Este formato no incluye el prefijo “Se produjo un error (ErrorCode):” para las excepciones de la CLI.

Ejemplo: Ausencia de configuración de la región

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

Ejemplo: Bucket de S3 inexistente

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

Los errores incluyen ahora sistemáticamente el prefijo aws: [ERROR]: para las excepciones de la CLI. Las versiones anteriores no siempre incluían este prefijo.

Las siguientes excepciones siempre utilizan el formato heredado, independientemente del formato de error configurado:

  • UnknownArgumentError: muestra la información de uso.

  • Interrupciones del teclado (KeyboardInterrupt)

Ejemplo completo

En el siguiente ejemplo se muestra un comando con formato de error JSON:

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

Salida (stderr):

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

El campo BucketName es un elemento de error modelado devuelto por el servicio Amazon S3.