Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Individuate la causa della mancata compilazione di un'immagine con contesto di errore
Quando la creazione di un'immagine non riesce, Image Builder riporta l'errore nell'immagine. `state` Lo stato contiene un messaggio che descrive l'errore e il **contesto di errore strutturato in `failureContext` esso**. `reason`
Il contesto di errore è un insieme di campi che denominano il flusso di lavoro, la fase del flusso di lavoro, la fase del componente e le regioni di destinazione coinvolte nell'errore. Poiché i campi sono strutturati, l'automazione può diramarsi direttamente su di essi ed è possibile passare i loro valori ad altre operazioni dell'API Image Builder per ottenere maggiori dettagli.
Image Builder restituisce il contesto di errore dalle operazioni [GetImage[ListImageBuildVersions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImageBuildVersions.html)](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetImage.html), e [ListImagePipelineImages](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListImagePipelineImages.html)API e lo visualizza in Image Builder. Console di gestione AWS
**Topics**
+ [Cosa contiene il contesto di errore](#image-failure-context-fields)
+ [Visualizza il contesto di errore per un'immagine fallita](#image-failure-context-view)
+ [Riconduci un errore alla sua causa principale](#image-failure-context-rca)
+ [Usa il contesto di errore con gli agenti AI](#image-failure-context-ai)
+ [Considerazioni](#image-failure-context-considerations)
## Cosa contiene il contesto di errore
Il contesto di errore descrive un errore a tre livelli. Ogni membro è facoltativo e Image Builder restituisce solo i membri che si applicano all'errore. Per i membri, i loro tipi e i loro vincoli, consulta la Guida di riferimento [ImageState](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ImageState.html)all'API *EC2 Image Builder*.
L'immagine
In quale fase si trovava l'immagine al momento dell'errore e in quale fase del flusso di lavoro e in quale fase del flusso di lavoro erano in esecuzione. Gli identificatori del flusso di lavoro e di esecuzione delle fasi hanno gli stessi valori che [ListWorkflowStepExecutions[GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)assumono, quindi è possibile passarli direttamente a tali operazioni.
La fase componente
Per un errore di compilazione o test causato da un componente, il componente che è stato eseguito, la fase e la fase all'interno del relativo documento, il modulo di AWSTOE azione eseguito dalla fase e l'errore segnalato dalla fase. Image Builder identifica il componente in base alla versione di build, quindi assegna un nome alla revisione esatta eseguita anche quando la ricetta fa riferimento a una versione con caratteri jolly. Per i moduli di azione, vedi. [Moduli d'azione supportati da AWSTOE gestore dei componenti](toe-action-modules.md)
Le regioni di destinazione
In caso di errore di distribuzione o integrazione, un errore di riepilogo per l'intera distribuzione e una voce per ogni destinazione non riuscita. Ogni voce riporta la data in cui è terminata la distribuzione, l'errore del servizio chiamato da Image Builder e, per una distribuzione tra account, la destinazione a cui Image Account AWS Builder ha distribuito. Quando la copia dell'AMI ha avuto successo, ma una fase successiva no, la voce indica anche quella fase: associazione delle configurazioni di licenza, aggiornamento dei modelli di avvio, inserimento dei parametri SSM, aggiornamento delle configurazioni Fast Launch di Amazon EC2 o esportazione dell'AMI. Le destinazioni che hanno avuto successo vengono omesse.
**Nota**
I membri restituiti da Image Builder dipendono dall'avanzamento della build. Un errore che si verifica prima che Image Builder avvii un workflow non ha alcun workflow da nominare. Ad esempio, se l'immagine principale della ricetta non esiste più, il contesto di errore identifica la fase e nient'altro.
Gli esempi illustrati [Visualizza il contesto di errore per un'immagine fallita](#image-failure-context-view) mostrano i membri che Image Builder restituisce in caso di errore di un componente e di distribuzione.
## Visualizza il contesto di errore per un'immagine fallita
**Visualizza il contesto dell'errore nella console Image Builder**
Image Builder visualizza i dettagli dell'errore di un'immagine ovunque mostri lo stato `Failed` dell'immagine.
1. Apri la console EC2 Image Builder [https://console.aws.amazon.com/imagebuilder/](https://console.aws.amazon.com/imagebuilder/)all'indirizzo.
1. Scegli **Immagini** dal pannello di navigazione, quindi scegli la versione di creazione dell'immagine non riuscita. Puoi anche aprire l'elenco delle **immagini di output** per una pipeline.
1. Scegliete lo stato `Failed` dell'immagine. Image Builder visualizza i dettagli dell'errore per l'immagine e collega la fase del flusso di lavoro non riuscita ai relativi dettagli di runtime.
**Ottieni il contesto dell'errore con AWS CLI**
Esegui il **get-image** comando con la versione di build ARN dell'immagine fallita.
```
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"
```
L'output di esempio seguente mostra una compilazione non riuscita perché una fase del componente ha eseguito uno script che è uscito con uno stato diverso da zero.
```
{
"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"
}
}
}
```
L'output di esempio successivo mostra un'immagine creata e testata con successo, poi fallita mentre Image Builder aggiornava i modelli di avvio in tre regioni di destinazione. La compilazione è riuscita in tutte le altre destinazioni, quindi vengono visualizzate solo le tre regioni non riuscite.
```
{
"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'"
}
]
}
}
}
```
Per trovare le build fallite in un account senza controllarle ognuna, elenca le versioni di build dell'immagine e filtra in base allo stato dell'immagine. L'esempio seguente restituisce le build fallite di un'immagine, con il contesto di errore per ciascuna di esse.
```
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]"
```
## Riconduci un errore alla sua causa principale
Il contesto di errore limita un errore a un singolo passaggio. Utilizza i seguenti passaggi per passare da quel passaggio alle prove che lo spiegano.
1. **Leggi `imageStatus` per scoprire la fase che è fallita.** Un valore di `BUILDING` o `TESTING` indica che l'errore si è verificato sull'istanza Amazon EC2 lanciata da Image Builder, quindi i log dei componenti sono la prossima cosa da consultare. Un valore di `DISTRIBUTING` o `INTEGRATING` indica che l'immagine è stata creata e l'errore è nelle impostazioni di distribuzione o in un account di destinazione o.
1. **Leggi il membro che descrive l'errore specifico.** Se `componentFailure` presente, identifica la fase non riuscita nel documento del componente, insieme all'azione eseguita e all'errore segnalato. Se `distributionFailure` è presente, ogni voce `regionFailures` fornisce una destinazione e il relativo errore.
1. **Esamina i dettagli del runtime del flusso di lavoro.** Chiama [ListWorkflowStepExecutions](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_ListWorkflowStepExecutions.html)con `workflowExecutionId` per vedere ogni passaggio del flusso di lavoro e dove rientra il passaggio non riuscito nella sequenza. Chiama [GetWorkflowStepExecution](https://docs.aws.amazon.com/imagebuilder/latest/APIReference/API_GetWorkflowStepExecution.html)with `stepExecutionId` per conoscere gli input, gli output e lo stato di rollback del passaggio fallito stesso.
L'esempio seguente elenca i passaggi per un'esecuzione non riuscita del flusso di lavoro.
```
aws imagebuilder list-workflow-step-executions \
--workflow-execution-id wf-{{a1b2c3d4-5678-90ab-cdef-EXAMPLE11111}}
```
1. **Leggete i registri relativi al passaggio non riuscito.** Usa `workflowExecutionId` e `failedStep` vai direttamente al percorso di registro relativo a quel passaggio. Per ulteriori informazioni, consulta [Ottieni l'output completo dei componenti dai log](#image-failure-context-logs).
1. **Se necessario, riproduci l'errore.** Per mantenere l'istanza di build in esecuzione in modo da potervi connettere, deselezionate l'impostazione **Terminate instance on failure** nella configurazione dell'infrastruttura utilizzata dalla pipeline. Per ulteriori informazioni, consulta [Risolvi i problemi relativi alle build della pipeline](troubleshooting.md#troubleshooting-pipelines).
### Ottieni l'output completo dei componenti dai log
Il contesto di errore riporta l'errore generato da una fase del componente, ma non lo standard output e l'errore standard dello script eseguito dal passaggio. Image Builder mantiene l'output nei log dei componenti.
Quando un componente si guasta, AWSTOE scrive i dettagli del primo passaggio non riuscito nel registro della console, seguiti dall'output di errore standard completo relativo a quel passaggio.
```
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`è lo stesso valore `componentFailure.componentArn` riportato, quindi usalo per abbinare il blocco di registro al contesto di errore di un'immagine. `Document`è quello dichiarato dal documento componente, `name` che l'autore sceglie indipendentemente dalla risorsa del componente, quindi i due possono differire e `Document` da soli non identificano quale componente ha avuto esito negativo.
AWSTOE scrive `ErrorMessage` e `Stderr` solo quando il passaggio fallito li ha prodotti.
Image Builder trasmette i log dei componenti ad CloudWatch Amazon Logs al termine della build. Se hai specificato un bucket Amazon S3 nella configurazione dell'infrastruttura, Image Builder li scrive anche lì. Per i nomi dei gruppi di log e degli stream, consulta. [Monitora i log di Image Builder con Amazon Logs CloudWatch](monitor-cwlogs.md) Per i file che AWSTOE produce e il contenuto di ognuno di essi, vedi[Registrazione dei componenti](toe-use-documents.md#component-logging).
## Usa il contesto di errore con gli agenti AI
Il contesto di errore è progettato per essere letto dall'automazione così come dalle persone. Un agente AI che risolve i problemi di una build fallita legge i campi denominati e ne usa i valori come argomenti per la successiva chiamata API che effettua. Ciò rende una diagnosi ripetibile e impedisce all'agente di indovinare su quale componente indagare.
È possibile utilizzare il contesto di errore in uno dei seguenti modi:
+ **Risoluzione dei problemi in Image Console di gestione AWS Builder: la** funzionalità di risoluzione dei problemi, fornita AWS DevOps da Agent, utilizza il contesto degli errori per analizzare la fase del flusso di lavoro e il componente che ha avuto esito negativo prima di esaminare i log e le risorse correlate. Per ulteriori informazioni, consulta [Risolvi i problemi relativi alle build fallite con AI - Preview](devops-agent-troubleshooting.md).
+ **Il tuo agente di codifica AI: un agente** che chiama `GetImage` riceve il contesto di errore nella risposta e può seguirlo allo stesso modo. Per fornire al tuo agente la conoscenza più ampia di Image Builder di cui ha bisogno per agire su ciò che trova, vedi. [Risolvi i problemi relativi alle build con un agente di codifica AI](agent-toolkit-skill.md)
Se costruisci la tua automazione sul contesto di errore, considera ogni membro come facoltativo e controlla i membri che utilizzi anziché la presenza dei `failureContext` membri stessi. I membri restituiti da Image Builder dipendono dall'errore e Image Builder può aggiungere membri nel tempo.
## Considerazioni
Quando si utilizza il contesto di errore, tenere presente quanto segue:
+ Image Builder restituisce il contesto di errore solo per le immagini che hanno avuto esito negativo. Un'immagine riuscita e un'immagine che hai cancellato non ce l'hanno.
+ Un'immagine fallita contiene entrambi `reason` e`failureContext`. Utilizzatelo `reason` per un riepilogo leggibile dell'errore e `failureContext` per localizzarlo.
+ Se un componente utilizza l'`ExecuteDocument`azione per eseguire un documento nidificato, il contesto di errore identifica il componente che Image Builder ha eseguito dalla ricetta, non il documento nidificato.
+ I messaggi di errore nel contesto di errore hanno una lunghezza limitata e possono essere troncati. I log dei componenti contengono l'output completo.
+ Il contesto di errore riporta il primo passaggio non riuscito. Se più di un passaggio non è riuscito, esamina le esecuzioni delle fasi del flusso di lavoro e i registri dei componenti per il resto.
+ I messaggi di errore possono contenere testo prodotto da un componente o da un altro AWS servizio. Trattali come input non attendibili se li renderizzi o li passi a un altro sistema.