# Solucionar problemas com o agente do EC2Launch v2
Esta seção mostra cenários comuns de solução de problemas para o EC2Launch v2, informações sobre como visualizar logs de eventos do Windows e saída e mensagens do log do console.
**Topics**
+ [Cenários comuns](#ec2launchv2-troubleshooting-scenarios)
+ [Logs de eventos do Windows](#ec2launchv2-windows-event-logs)
+ [Saída do log do console do EC2Launch v2](#ec2launchv2-console-output)
## Cenários comuns de solução de problemas
Esta seção mostra cenários comuns de solução de problemas e etapas para resolução.
**Topics**
+ [Falha no serviço ao definir o papel de parede](#ec2launchv2-troubleshooting-wallpaper)
+ [Falha no serviço ao executar dados do usuário](#ec2launchv2-troubleshooting-user-data)
+ [O serviço executa uma tarefa apenas uma vez](#ec2launchv2-troubleshooting-task-once)
+ [Falha no serviço ao executar uma tarefa](#ec2launchv2-troubleshooting-task-failed)
+ [O serviço executa dados do usuário mais de uma vez](#ec2launchv2-troubleshooting-user-data-more-than-once)
+ [As tarefas agendadas do EC2Launch v1 não conseguem ser executadas após a migração para o EC2Launch v2](#ec2launchv2-troubleshooting-scheduled-tasks-migration)
+ [O serviço inicializa um volume do EBS que não está vazio](#ec2launchv2-troubleshooting-ebs-initialize)
+ [`setWallpaper`A tarefa não está ativada, mas o papel de parede é redefinido na reinicialização](#ec2launchv2-troubleshooting-wallpaper-resets)
+ [Serviço preso no status em execução](#ec2launchv2-troubleshooting-service-stuck-running)
+ [Um `agent-config.yml` inválido impede a abertura da caixa de diálogo de configurações do EC2Launch v2](#ec2launchv2-troubleshooting-invalid-agent-config)
+ [`task:executeScript should be unique and only invoked once`](#ec2launchv2-troubleshooting-executescript)
### Falha no serviço ao definir o papel de parede
**Resolução**
1. Verifique se `%AppData%\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\setwallpaper.lnk` existe.
1. Verifique `%ProgramData%\Amazon\EC2Launch\log\agent.log` para saber se ocorreram erros.
### Falha no serviço ao executar dados do usuário
**Causa possível**: a falha no serviço pode ter ocorrido antes da execução dos dados do usuário.
**Resolução**
1. Verifique `%ProgramData%\Amazon\EC2Launch\state\previous-state.json`.
1. Veja se `boot`, `network`, `preReady` e `postReadyLocalData` foram todos marcados como sucesso.
1. Se um dos estágios falhar, verifique se há erros específicos `%ProgramData%\Amazon\EC2Launch\log\agent.log`.
### O serviço executa uma tarefa apenas uma vez
**Resolução**
1. Verifique a frequência da tarefa.
1. Se o serviço já tiver sido executado após Sysprep e a frequência da tarefa estiver definida como `once`, a tarefa não será executada novamente.
1. Defina a frequência da tarefa como `always` se você quiser que ela execute a tarefa sempre que o EC2Launch v2 for executado.
### Falha no serviço ao executar uma tarefa
**Resolução**
1. Verifique as entradas mais recentes em `%ProgramData%\Amazon\EC2Launch\log\agent.log`.
1. Se não ocorrerem erros, tente executar o serviço manualmente a partir de `"%ProgramFiles%\Amazon\EC2Launch\EC2Launch.exe" run` para ver se as tarefas foram bem-sucedidas.
### O serviço executa dados do usuário mais de uma vez
**Resolução**
Os dados do usuário são tratados de forma diferente entre o EC2Launch v1 e o EC2Launch v2. O EC2Launch v1 executa dados do usuário como uma tarefa programada na instância quando `persist` for definido como `true`. Se `persist` estiver definido como `false`, a tarefa não será programada mesmo quando ela sair com uma reinicialização ou for interrompida durante a execução.
EC2Launch v2 executa dados do usuário como uma tarefa de agente e rastreia seu estado de execução. Se os dados do usuário emitirem uma reinicialização do computador ou se os dados do usuário tiverem sido interrompidos durante a execução, o estado de execução persistirá `pending` e os dados do usuário serão executados novamente na próxima inicialização da instância. Se você quiser impedir que o script de dados do usuário seja executado mais de uma vez, torne o script idempotente.
O exemplo a seguir de script idempotente define o nome do computador e se junta a um domínio.
```
$name = $env:computername
if ($name -ne $desiredName) {
Rename-Computer -NewName $desiredName
}
$domain = Get-ADDomain
if ($domain -ne $desiredDomain)
{
Add-Computer -DomainName $desiredDomain
}
$telnet = Get-WindowsFeature -Name Telnet-Client
if (-not $telnet.Installed)
{
Install-WindowsFeature -Name "Telnet-Client"
}
false
```
### As tarefas agendadas do EC2Launch v1 não conseguem ser executadas após a migração para o EC2Launch v2
**Resolução**
A ferramenta de migração não detecta qualquer tarefa agendada vinculada aos scripts do EC2Launch v1; portanto, ela não configura automaticamente essas tarefas no EC2Launch v2. Para configurar essas tarefas, edite o arquivo [`agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-task-configuration) ou use a [caixa de diálogo de configurações do EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-ui). Por exemplo, se uma instância tiver uma tarefa agendada que executa `InitializeDisks.ps1`, depois de executar a ferramenta de migração, você deverá especificar os volumes que deseja inicializar na caixa de diálogo de configurações do EC2Launch v2. Consulte a Etapa 6 do procedimento para [Alterar configurações usando a caixa de diálogo de configurações do EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-ui).
### O serviço inicializa um volume do EBS que não está vazio
**Resolução**
Antes de inicializar um volume, o EC2Launch v2 tenta detectar se ele está vazio. Se um volume não estiver vazio, ele ignorará a inicialização. Quaisquer volumes detectados como não vazios não são inicializados. Um volume é considerado vazio se seus primeiros 4 KiB estiverem vazios ou se o volume não tiver um [layout de unidade reconhecível pelo Windows](https://learn.microsoft.com/en-us/windows/win32/api/winioctl/ns-winioctl-drive_layout_information_ex). Um volume que foi inicializado e formatado em um sistema Linux não tem um layout de unidade reconhecível pelo Windows, por exemplo MBR ou GPT. Portanto, ele será considerado vazio e será inicializado. Se você quiser preservar esses dados, não confie na detecção de unidade vazia do EC2Launch v2. Em vez disso, especifique os volumes que você gostaria de inicializar na [caixa de diálogo de configurações do EC2Launch v2](ec2launch-v2-settings.md#ec2launch-v2-ui) (consulte a etapa 6) ou no [`agent-config.yml`](ec2launch-v2-task-definitions.md#ec2launch-v2-initializevolume).
### `setWallpaper`A tarefa não está ativada, mas o papel de parede é redefinido na reinicialização
A tarefa `setWallpaper` cria o arquivo de atalho `setwallpaper.lnk` na pasta de startup de cada usuário existente. Esse arquivo de atalho é executado quando o usuário faz login pela primeira vez após a inicialização da instância. Ele configura a instância com um papel de parede personalizado que exibe os atributos da instância. Remover a tarefa `setWallpaper` não exclui esse arquivo de atalho. Exclua esse arquivo manualmente ou excluí-lo usando um script.
O caminho do atalho é:
`$env:SystemDrive/Users//AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk`
**Resolução**
Exclua esse arquivo manualmente ou exclua-o usando um script.
**Exemplo de script PowerShell para excluir arquivo de atalho**
```
foreach ($userDir in (Get-ChildItem "C:\Users" -Force -Directory).FullName)
{
$startupPath = Join-Path $userDir -ChildPath "AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup"
if (Test-Path $startupPath)
{
$wallpaperSetupPath = Join-Path $startupPath -ChildPath "setwallpaper.lnk"
if (Test-Path $wallpaperSetupPath)
{
Remove-Item $wallpaperSetupPath -Force -Confirm:$false
}
}
}
```
### Serviço preso no status em execução
**Descrição**
O EC2Launch v2 é bloqueado com mensagens de log (`agent.log`) semelhantes às seguintes:
```
2022-02-24 08:08:58 Info: *****************************************************************************************
2022-02-24 08:08:58 Info: EC2Launch Service starting
2022-02-24 08:08:58 Info: Windows event custom log exists: Amazon EC2Launch
2022-02-24 08:08:58 Info: ACPI SPCR table not supported. Bailing Out
2022-02-24 08:08:58 Info: Serial port is in use. Waiting for Serial Port...
2022-02-24 08:09:00 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:02 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:04 Info: ACPI SPCR table not supported. Use default console port.
2022-02-24 08:09:06 Info: ACPI SPCR table not supported. Use default console port.
```
**Possível causa**
O SAC está habilitado e usando a porta serial. Para mais informações, consulte [Use SAC to troubleshoot your Windows instance](troubleshoot-using-serial-console.md#troubleshooting-sac) (Usar o SAC para solucionar problemas de instâncias do Windows).
**Resolução**
Tente as seguintes etapas para resolver esse problema:
+ Desative o serviço que está usando a porta serial.
+ Se quiser que o serviço continue usando a porta serial, crie scripts personalizados para executar tarefas do agente de execução e invoque-os como tarefas agendadas.
### Um `agent-config.yml` inválido impede a abertura da caixa de diálogo de configurações do EC2Launch v2
**Descrição**
As configurações do EC2Launch v2 tentam analisar o arquivo `agent-config.yml` antes de abrir a caixa de diálogo. Se o arquivo de configuração YAML não seguir o esquema compatível, a caixa de diálogo exibirá o seguinte erro:
`Unable to parse configuration file agent-config.yml. Review configuration file. Exiting application.`
**Resolução**
1. Verifique se o arquivo de configuração segue o [esquema compatível](ec2launch-v2-settings.md#ec2launch-v2-schema-agent-config).
1. Para começar do zero, copie o arquivo de configuração padrão no `agent-config.yml`. Você pode usar o [exemplo `agent-config.yml`](ec2launch-v2-settings.md#ec2launch-v2-example-agent-config) fornecido na seção Configuração da tarefa.
1. Também é possível recomeçar excluindo o `agent-config.yml`. As configurações do EC2Launch v2 geram um arquivo de configuração vazio.
### `task:executeScript should be unique and only invoked once`
**Descrição**
Não é possível repetir uma tarefa na mesma etapa.
**Resolução**
Algumas tarefas devem ser inseridas como uma matriz, como [**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript) e [**executeProgram**](ec2launch-v2-task-definitions.md#ec2launch-v2-executeprogram). Para obter um exemplo de como escrever o script como uma matriz, consulte [**executeScript**](ec2launch-v2-task-definitions.md#ec2launch-v2-executescript).
## Logs de eventos do Windows
O EC2Launch v2 publica logs de eventos do Windows para eventos importantes, como a inicialização do serviço, o Windows pronto, e o sucesso e a falha da tarefa. Identificadores de eventos identificam exclusivamente um evento específico. Cada evento contém informações de estágio, tarefa e nível e uma descrição. É possível definir gatilhos para eventos específicos usando o identificador de eventos.
Os IDs de evento fornecem informações sobre um evento e identificam alguns eventos de forma exclusiva. O dígito menos significativo de um ID de evento indica a gravidade de um evento.
| Evento | Dígito menos significativo |
| --- | --- |
| Success | . . .0 |
| Informational | . . .1 |
| Warning | . . .2 |
| Error | . . .3 |
Os eventos relacionados ao serviço, gerados quando o serviço é iniciado ou interrompido, incluem um identificador de evento de um dígito.
| Evento | Identificador de um dígito |
| --- | --- |
| Success | 0 |
| Informational | 1 |
| Warning | 2 |
| Error | 3 |
As mensagens de evento para eventos do `EC2LaunchService.exe` começam com `Service:`. As mensagens de evento para eventos do `EC2Launch.exe` não começam com `Service:`.
Os IDs de evento de quatro dígitos incluem informações sobre o estado, a tarefa e a gravidade de um evento.
**Topics**
+ [Formato de ID do evento](#ec2launchv2-windows-event-logs-format)
+ [Exemplos de ID de evento](#ec2launchv2-windows-event-logs-id-examples)
+ [Esquema de log de eventos do Windows](#ec2launch-v2-windows-event-logs-schema)
### Formato de ID do evento
A tabela a seguir mostra o formato de um identificador de eventos do EC2Launch v2.
| 3 | 2 1 | 0 |
| --- | --- | --- |
| S | T | L |
As letras e números na tabela representam o tipo de evento e as definições a seguir.
| Tipo de evento | Definição |
| --- | --- |
| S (Estágio) | 0 - Mensagem de nível de serviço 1 - Inicialização 2 - Rede 3 - PreReady 5 - O Windows está pronto 6 - PostReady 7 - Dados do usuário |
| T (Tarefa) | As tarefas representadas pelos dois valores correspondentes são diferentes para cada estágio. Para visualizar a lista completa de eventos, consulte [Esquema de log de eventos do Windows](#ec2launch-v2-windows-event-logs-schema). |
| L (Nível do evento) | 0 - Êxito 1 - Informativo 2 - Aviso 3 - Erro |
### Exemplos de ID de evento
Veja a seguir alguns exemplos de IDs de evento.
+ `5000` - o Windows está pronto para ser usado
+ `3010` - êxito ao ativar a tarefa do Windows no estágio PreReady
+ `6013` - A tarefa Definir papel de parede no estágio PostReady Local Data encontrou um erro
### Esquema de log de eventos do Windows
| MessageId/ID do evento | Mensagem do evento |
| --- | --- |
| . . .0 | Success |
| . . .1 | Informational |
| . . .2 | Warning |
| . . .3 | Error |
| x | EC2Launch service-level logs |
| 0 | EC2Launch service exited successfully |
| 1 | EC2Launch service informational logs |
| 2 | EC2Launch service warning logs |
| 3 | EC2Launch service error logs |
| 10 | Replace state.json with previous-state.json |
| 100 | Serial Port |
| 200 | Sysprep |
| 300 | PrimaryNic |
| 400 | Metadata |
| x000 | Stage (1 digit), Task (2 digits), Status (1 digit) |
| 1000 | Boot |
| 1010 | Boot - extend\$1root\$1partition |
| 2000 | Network |
| 2010 | Network - add\$1routes |
| 3000 | PreReady |
| 3010 | PreReady - activate\$1windows |
| 3020 | PreReady - install\$1egpu\$1manager |
| 3030 | PreReady - set\$1monitor\$1on |
| 3040 | PreReady - set\$1hibernation |
| 3050 | PreReady - set\$1admin\$1account |
| 3060 | PreReady - set\$1dns\$1suffix |
| 3070 | PreReady - set\$1wallpaper |
| 3080 | PreReady - set\$1update\$1schedule |
| 3090 | PreReady - output\$1log |
| 3100 | PreReady - enable\$1open\$1ssh |
| 5000 | Windows is Ready to use |
| 6000 | PostReadyLocalData |
| 7000 | PostReadyUserData |
| 6010/7010 | PostReadyLocal/UserData - set\$1wallpaper |
| 6020/7020 | PostReadyLocal/UserData - set\$1update\$1schedule |
| 6030/7030 | PostReadyLocal/UserData - set\$1hostname |
| 6040/7040 | PostReadyLocal/UserData - execute\$1program |
| 6050/7050 | PostReadyLocal/UserData - execute\$1script |
| 6060/7060 | PostReadyLocal/UserData - manage\$1package |
| 6070/7070 | PostReadyLocal/UserData - initialize\$1volume |
| 6080/7080 | PostReadyLocal/UserData - write\$1file |
| 6090/7090 | PostReadyLocal/UserData - start\$1ssm |
| 7100 | PostReadyUserData - enable\$1open\$1ssh |
| 6110/7110 | PostReadyLocal/UserData - enable\$1jumbo\$1frames |
## Saída do log do console do EC2Launch v2
Esta seção contém uma saída de log do console de exemplo para EC2Launch v2 e lista todas as mensagens de erro de log do console do EC2Launch v2 para ajudar você a solucionar problemas. Para obter mais informações sobre a saída do console da instância e como acessá-la, consulte [Saída do console da instância](troubleshoot-unreachable-instance.md#instance-console-console-output).
**Topics**
+ [Saída do log do console do EC2Launch v2](#ec2launchv2-console-log-output)
+ [Mensagens de log do console do EC2Launch v2](#ec2launchv2-console-log-messages)
### Saída do log do console do EC2Launch v2
Veja a seguir um exemplo de saída de log do console para EC2Launch v2. Alguns valores nesse exemplo são substituídos por texto representativo entre chaves.
```
2025/07/22 21:26:53Z: Windows sysprep configuration complete.
2025/07/22 21:26:53Z: Message: Waiting for access to metadata...
2025/07/22 21:26:53Z: Message: Meta-data is now available.
2025/07/22 21:26:53Z: AMI Origin Version: 2024.12.13
2025/07/22 21:26:53Z: AMI Origin Name: Windows_Server-2022-English-Full-Base
2025/07/22 21:26:53Z: OS: Microsoft Windows NT 10.0.20348
2025/07/22 21:26:53Z: OsVersion: 10.0
2025/07/22 21:26:53Z: OsProductName: Windows Server 2022 Datacenter
2025/07/22 21:26:53Z: OsBuildLabEx: 20348.1.amd64fre.fe_release.210507-1500
2025/07/22 21:26:53Z: OsCurrentBuild: 20348
2025/07/22 21:26:53Z: OsReleaseId: 2009
2025/07/22 21:26:53Z: Language: en-US
2025/07/22 21:26:53Z: TimeZone: UTC
2025/07/22 21:26:53Z: Offset: UTC +0000
2025/07/22 21:26:53Z: Launch: EC2 Launch v2.2.63
2025/07/22 21:26:53Z: AMI-ID: ami-1234567890abcdef1
2025/07/22 21:26:53Z: Instance-ID: i-1234567890abcdef0
2025/07/22 21:26:54Z: Instance Type: t3.xlarge
2025/07/22 21:26:54Z: Driver: AWS NVMe Driver v1.6.0.35
2025/07/22 21:26:54Z: SubComponent: 1.6.0.35; EnableSCSIPersistentReservations: 0
2025/07/22 21:26:54Z: Driver: AWS PV Driver Package v8.5.0
2025/07/22 21:26:55Z: Driver: Amazon Elastic Network Adapter v2.8.0.0
2025/07/22 21:26:55Z: HOSTNAME: EC2AMAZ-9FJG5CC
2025/07/22 21:26:55Z: RDPCERTIFICATE-SUBJECTNAME: {certificate subject name}
2025/07/22 21:26:55Z: RDPCERTIFICATE-THUMBPRINT: {thumbprint hash}
2025/07/22 21:26:56Z: SSM: Amazon SSM Agent v3.3.2746.0
2025/07/22 21:26:57Z: User data format: no_user_data
2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsTelemetryEnabled=true
2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentOsArch=windows_amd64
2025/07/22 21:26:57Z: EC2LaunchTelemetry: IsAgentScheduledPerBoot=true
2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentCommandErrorCode=1
2025/07/22 21:26:57Z: EC2LaunchTelemetry: AdminPasswordTypeCode=0
2025/07/22 21:26:57Z: EC2LaunchTelemetry: AgentErrorLocation=execute_windows.go:410
2025/07/22 21:26:57Z: EC2LaunchTelemetry: IpConflictDetectionCode=0
2025/07/22 21:26:57Z: Message: Windows is Ready to use
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...}
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2", ...}
```
### Mensagens de log do console do EC2Launch v2
Veja a seguir uma lista de todas as mensagens de log do console do EC2Launch v2.
```
Error EC2Launch service is stopping. {error message}
```
Detalhes do erro do serviço interrompido:
+ `Error setting up EC2Launch agent folders`
+ `See instance logs for detail`
+ `Error stopping service`
+ `Error initializing service`
```
Windows sysprep configuration complete
```
```
Invalid administrator username: {invalid username}
```
```
Invalid administrator password
Username: {username}
Password: {encrypted password}
```
A mensagem a seguir é um bloco de informações contendo detalhes da AMI:
```
AMI Origin Version: {amiVersion}
AMI Origin Name: {amiName}
Microsoft Windows NT {currentVersion}.{currentBuildNumber}
OsVersion: {currentVersion}
OsProductName: {productName}
OsBuildLabEx: {buildLabEx}
OsCurrentBuild: {currentBuild}
OsReleaseId: {releaseId}
Language: {language}
TimeZone: {timeZone}
Offset: UTC {offset}
Launch agent: EC2Launch {BuildVersion}
AMI-ID: {amiId}
Instance-ID: {instanceId}
Instance Type: {instanceType}
HOSTNAME: {computer name}
RDPCERTIFICATE-SUBJECTNAME: {certificate subject name}
RDPCERTIFICATE-THUMBPRINT: {thumbprint hash}
SqlServerBilling: {sql billing}
SqlServerInstall: {sql patch leve, edition type}
Driver: AWS NVMe Driver {version}
Driver: Inbox NVMe Driver {version}
Driver: AWS PV Driver Package {version}
SSM: Amazon SSM Agent {version}
AWS VSS Version: {version}
```
```
Windows sysprep configuration complete.
Windows is being configured. 'SysprepState is {state}'
Windows is still being configured. 'SysprepState is {state}'
Windows is Ready to use
Waiting for access to metadata...
Meta-data is now available.
Metadata is not available for this instance.
Timed out waiting for access to metadata.
User data format: {format}
```
As mensagens de telemetria do EC2Launch v2 incluem os valores das propriedades de telemetria de inicialização. A partir da versão 2.2.63, os dados de telemetria do EC2 Agent são formatados como um objeto JSON.
```
EC2LaunchTelemetry: {telemetry property}
```
```
{"type":"EC2AgentTelemetry","agentId":"WindowsLaunchAgentV2" ... }
```