Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Encuentre la causa de un error en la creación de una imagen con el contexto del error
Cuando se produce un error en la creación de una imagen, Image Builder informa del error en la imagen`state`. El estado contiene un mensaje que describe el `reason` error y el **contexto estructurado del error**`failureContext`.
El contexto de error es un conjunto de campos que nombran el flujo de trabajo, el paso del flujo de trabajo, el paso del componente y las regiones de destino implicadas en el error. Como los campos están estructurados, la automatización puede ramificarlos directamente y usted puede pasar sus valores a otras operaciones de la API de Image Builder para obtener más detalles.
Image Builder devuelve el contexto de error de las operaciones [GetImage[ListImageBuildVersions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImageBuildVersions.html)](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetImage.html), y de la [ListImagePipelineImages](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImagePipelineImages.html)API y lo muestra en Image Builder Consola de administración de AWS.
**Topics**
+ [Qué contiene el contexto de error](#image-failure-context-fields)
+ [Vea el contexto de error de una imagen defectuosa](#image-failure-context-view)
+ [Rastrea un error hasta su causa raíz](#image-failure-context-rca)
+ [Utilice el contexto de fallos con los agentes de IA](#image-failure-context-ai)
+ [Consideraciones](#image-failure-context-considerations)
## Qué contiene el contexto de error
El contexto de fallo describe un fallo en tres niveles. Todos los miembros son opcionales e Image Builder devuelve solo los miembros que se aplican al error. Para conocer los miembros, sus tipos y sus restricciones, consulte la referencia de [ImageState](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageState.html)la *API de EC2 Image Builder*.
La imagen
En qué etapa se encontraba la imagen cuando falló y qué flujo de trabajo y paso del flujo de trabajo se estaban ejecutando. Los identificadores del flujo de trabajo y de la ejecución de los pasos tienen los mismos valores que [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)y [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html), por lo tanto, puede pasarlos directamente a esas operaciones.
El paso que lo compone
En el caso de un error de compilación o prueba provocado por un componente, el componente que se ejecutó, la fase y el paso de su documento, el módulo de TOE de AWS acción que ejecutó el paso y el error que notificó el paso. Image Builder identifica el componente por versión de compilación, por lo que asigna un nombre a la revisión exacta que se ejecutó incluso cuando la receta haga referencia a una versión comodín. Para ver los módulos de acción, consulte[Módulos de acción respaldados por TOE de AWS administrador de componentes](toe-action-modules.md).
Las regiones de destino
En el caso de un error de distribución o integración, un error de resumen para la distribución en su conjunto y una entrada para cada destino que haya fallado. Cada entrada incluye la forma en que terminó la distribución, el error del servicio al que llamó Image Builder y, en el caso de una distribución multicuenta, el destino al Cuenta de AWS que se distribuyó Image Builder. Si la copia de la AMI se realizó correctamente, pero un paso posterior no, la entrada también nombra ese paso: asociar las configuraciones de licencia, actualizar las plantillas de lanzamiento, colocar los parámetros de SSM, actualizar las configuraciones de Amazon EC2 Fast Launch o exportar la AMI. Los destinos que se realizaron correctamente se omiten.
**nota**
Los miembros que devuelve Image Builder dependen del progreso de la creación. Si se produce un error antes de que Image Builder inicie un flujo de trabajo, no se puede nombrar ningún flujo de trabajo. Por ejemplo, si la imagen principal de la receta ya no existe, el contexto del error identifica la etapa y nada más.
En los ejemplos que se [Vea el contexto de error de una imagen defectuosa](#image-failure-context-view) muestran a continuación, se muestran los miembros que Image Builder devuelve por un error de componente y por un error de distribución.
## Vea el contexto de error de una imagen defectuosa
**Ver el contexto del error en la consola de Image Builder**
Image Builder muestra los detalles de error de una imagen siempre que muestre el estado de `Failed` la imagen.
1. Abra la consola [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)EC2 Image Builder en.
1. Seleccione **Imágenes** en el panel de navegación y, a continuación, elija la versión de creación de imágenes fallida. También puedes abrir la lista **de imágenes de salida** de una canalización.
1. Seleccione el estado `Failed` de la imagen. Image Builder muestra los detalles del error de la imagen y vincula el paso del flujo de trabajo fallido con sus detalles de tiempo de ejecución.
**Obtenga el contexto del fallo con el AWS CLI**
Ejecute el **get-image** comando con el ARN de la versión de compilación de la imagen fallida.
```
aws imagebuilder get-image \
--image-build-version-arn arn:aws:imagebuilder:{{us-west-2}}:{{123456789012}}:image/{{my-example-recipe}}/1.0.0/1 \
--query "image.state"
```
El siguiente ejemplo de resultado muestra una compilación que falló porque en un paso de un componente se ejecutó un script cuyo estado era distinto de cero.
```
{
"status": "FAILED",
"reason": "Workflow Execution ID: 'wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111' failed with reason: Document arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1 failed!",
"failureContext": {
"imageStatus": "BUILDING",
"workflowExecutionId": "wf-a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"workflowArn": "arn:aws:imagebuilder:us-west-2:aws:workflow/build/build-image/{{x.x.x/x}}",
"stepExecutionId": "step-a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
"failedStep": "ApplyBuildComponents",
"componentFailure": {
"componentArn": "arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1",
"phaseName": "build",
"stepName": "InstallPackages",
"action": "ExecuteBash",
"errorMessage": "exit status 1"
}
}
}
```
El siguiente ejemplo de salida muestra una imagen que se creó y probó correctamente, pero que falló mientras Image Builder actualizaba las plantillas de lanzamiento en tres regiones de destino. La creación se realizó correctamente en todos los demás destinos, por lo que solo aparecen las tres regiones fallidas.
```
{
"status": "FAILED",
"reason": "Integration failed with JobId 'a1b2c3d4-5678-90ab-cdef-EXAMPLE33333', status = 'Failed' for ARN 'arn:aws:imagebuilder:us-west-2:123456789012:image/my-example-recipe/1.0.0/1'. …",
"failureContext": {
"imageStatus": "INTEGRATING",
"distributionFailure": {
"errorMessage": "In region 'eu-west-1' - 'EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'' …",
"regionFailures": [
{
"region": "eu-west-1",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-0a1b2c3d4EXAMPLE' does not exist'"
},
{
"region": "us-east-1",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-1a2b3c4d5EXAMPLE' does not exist'"
},
{
"region": "us-east-2",
"status": "FAILED",
"imageConfigurationStep": "UPDATE_LAUNCH_TEMPLATES",
"errorMessage": "EC2 Client Error: 'The launch-template ID 'lt-2a3b4c5d6EXAMPLE' does not exist'"
}
]
}
}
}
```
Para encontrar las compilaciones fallidas en una cuenta sin inspeccionar cada una de ellas, haz una lista de las versiones de creación de imágenes y filtra según el estado de la imagen. En el siguiente ejemplo, se devuelven las compilaciones fallidas de una imagen, con el contexto de error de cada una de ellas.
```
aws imagebuilder list-image-build-versions \
--image-version-arn arn:aws:imagebuilder:{{us-west-2}}:{{123456789012}}:image/{{my-example-recipe}}/1.0.0 \
--query "imageSummaryList[?state.status=='FAILED'].[arn, state.failureContext]"
```
## Rastrea un error hasta su causa raíz
El contexto del error reduce el error a un solo paso. Utilice los siguientes pasos para pasar de ese paso a la evidencia que lo explica.
1. **Lee `imageStatus` para encontrar la etapa que falló.** Un valor igual `BUILDING` o `TESTING` significa que el error se produjo en la instancia de Amazon EC2 que lanzó Image Builder, por lo que los registros de los componentes son el siguiente lugar donde buscar. Un valor igual `DISTRIBUTING` o `INTEGRATING` significa que la imagen se creó y el error se encuentra en la configuración de distribución o en una cuenta de destino o.
1. **Lea el elemento que describe el error específico.** Si `componentFailure` está presente, identifica el paso fallido en el documento de componentes, junto con la acción que ejecutó el paso y el error registrado. Si `distributionFailure` está presente, cada entrada `regionFailures` proporciona un destino y su propio error.
1. **Inspeccione los detalles del tiempo de ejecución del flujo de trabajo.** Llame [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)`workflowExecutionId`para ver cada paso del flujo de trabajo y en qué lugar de la secuencia se encuentra el paso fallido. Consulte [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)con nosotros `stepExecutionId` para obtener información sobre las entradas, las salidas y el estado de reversión del propio paso fallido.
En el siguiente ejemplo, se enumeran los pasos necesarios para ejecutar un flujo de trabajo fallido.
```
aws imagebuilder list-workflow-step-executions \
--workflow-execution-id wf-{{a1b2c3d4-5678-90ab-cdef-EXAMPLE11111}}
```
1. **Lea los registros del paso fallido.** Utilice `workflowExecutionId` y `failedStep` para ir directamente a la ruta de registro de ese paso. Para obtener más información, consulte [Obtén el resultado completo de los componentes a partir de los registros](#image-failure-context-logs).
1. **Reproduzca el error si es necesario.** Para mantener la instancia de compilación en ejecución y poder conectarte a ella, desactiva la opción **Finalizar instancia en caso de error** en la configuración de infraestructura que utiliza tu canalización. Para obtener más información, consulte [Solución de problemas de canalizaciones](troubleshooting.md#troubleshooting-pipelines).
### Obtén el resultado completo de los componentes a partir de los registros
El contexto de error indica el error que generó un paso de un componente, pero no el resultado estándar ni el error estándar del script que ejecutó el paso. Image Builder guarda esa salida en los registros de los componentes.
Cuando se produce un error en un componente, TOE de AWS escribe los detalles del primer paso fallido en el registro de la consola, seguido del resultado de error estándar completo de ese paso.
```
Document: MyExampleDocument
ComponentArn: arn:aws:imagebuilder:us-west-2:123456789012:component/my-example-component/1.0.0/1
Phase: build
Step: InstallPackages
Action: ExecuteBash
ErrorMessage: exit status 1
Stderr: {{the full standard error output of the step}}
```
`ComponentArn`es el mismo valor que se `componentFailure.componentArn` indica, así que úselo para hacer coincidir el bloque de registro con el contexto de error de una imagen. `Document`es el `name` que se declara en el documento del componente y que el autor elige independientemente del recurso del componente, por lo que ambos pueden diferir y, `Document` por sí solo, no identifica qué componente ha fallado.
TOE de AWS escribe `ErrorMessage` y `Stderr` solo cuando el paso fallido los produjo.
Image Builder transmite los registros de los componentes a Amazon CloudWatch Logs cuando se completa la compilación. Si especificó un bucket de Amazon S3 en la configuración de su infraestructura, Image Builder también lo escribirá allí. Para ver los nombres de los grupos de registros y de las transmisiones, consulte[Supervise los registros de Image Builder con Amazon CloudWatch Logs](monitor-cwlogs.md). Para ver los archivos que TOE de AWS produce y el contenido de cada uno de ellos, consulte[Registro de componentes](toe-use-documents.md#component-logging).
## Utilice el contexto de fallos con los agentes de IA
El contexto del fallo está diseñado para que lo lean tanto la automatización como las personas. Un agente de IA que soluciona problemas en una compilación fallida lee los campos con nombre y usa sus valores como argumentos para la siguiente llamada a la API que realice. Esto hace que el diagnóstico sea repetible y evita que el agente adivine qué componente debe investigar.
Puede utilizar el contexto de error de cualquiera de las siguientes maneras:
+ **Solución de problemas en Image Builder Consola de administración de AWS**: la función de solución de problemas, impulsada por AWS DevOps Agent, utiliza el contexto del error para analizar el paso y el componente del flujo de trabajo que falló antes de examinar los registros y los recursos relacionados. Para obtener más información, consulte [Solucione problemas de compilaciones fallidas con IA: vista previa](devops-agent-troubleshooting.md).
+ **Su propio agente de codificación de IA**: un agente que llama `GetImage` recibe el contexto del error en la respuesta y puede rastrearlo de la misma manera. Para ofrecer a su agente los conocimientos más amplios de Image Builder que necesita para actuar en función de lo que encuentre, consulte[Solucione problemas de compilaciones con un agente de codificación de IA](agent-toolkit-skill.md).
Si crea su propia automatización en un contexto de fracaso, trate a todos los miembros como opcionales y compruebe los miembros que utiliza y no la presencia de ellos `failureContext` mismos. Los miembros que devuelve Image Builder dependen del error, y Image Builder puede añadir miembros con el tiempo.
## Consideraciones
Tenga en cuenta lo siguiente cuando utilice el contexto de error:
+ Image Builder devuelve el contexto de error solo para las imágenes que han fallado. Una imagen correcta y una imagen que haya cancelado no lo tienen.
+ Una imagen defectuosa contiene las dos `reason` palabras y`failureContext`. Se utiliza `reason` para obtener un resumen legible del error y `failureContext` para localizarlo.
+ Si un componente utiliza la `ExecuteDocument` acción para ejecutar un documento anidado, el contexto de error identifica el componente que Image Builder ejecutó a partir de su receta, no el documento anidado.
+ Los mensajes de error en un contexto de error tienen una longitud limitada y se pueden truncar. Los registros de los componentes contienen la salida completa.
+ El contexto de error indica el primer paso que falló. Si falló más de un paso, revise las ejecuciones de los pasos del flujo de trabajo y los registros de los componentes para ver el resto.
+ Los mensajes de error pueden contener texto generado por un componente u otro AWS servicio. Trátelos como una entrada que no sea de confianza si los procesa o los pasa a otro sistema.