[Quick Tip] Checking the behavior when configuration application fails with CloudWatch Agent on Windows

Hello, I'm Hayashi.

I installed the CloudWatch Agent on a Windows Server EC2 instance and applied the configuration file using fetch-config with amazon-cloudwatch-agent-ctl.ps1. When automating this process with user data or SSM Run Command, it's important to decide in advance how to detect failures in configuration application.

I was curious whether the status output could be used to determine if the configuration was applied successfully, so I investigated the behavior for each failure pattern.

Test Environment

The following command is used to apply the configuration.

& 'C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1' `
  -a fetch-config -m ec2 `
  -c file:'C:\ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.json' -s

Test Patterns

I ran fetch-config under 4 patterns with different configuration file states.
For reference, I also checked the case where the agent is started with amazon-cloudwatch-agent-ctl.ps1 -m ec2 -a start without running fetch-config.

The following 4 items were checked for each pattern.

• Exit code ($LASTEXITCODE)
• PowerShell exception
• status output
• Contents of the Configs folder

In amazon-cloudwatch-agent-ctl.ps1, configuration file validation is performed by the agent executable (amazon-cloudwatch-agent.exe), while service startup is handled within the script.

Configuration file validation errors appear in the executable's exit code ($LASTEXITCODE), while service startup failures are output as PowerShell exceptions.

For this reason, both the exit code and exceptions are included as items to check.

Test Results

Three findings emerged from the results.

status Can Appear Normal Even When Application Fails

Running -a start with no configuration file started the agent with default settings, along with the following output.

amazon-cloudwatch-agent is not configured. Applying amazon-cloudwatch-agent default configuration.

The status at this point was identical to when a correct configuration file was applied.

{
  "status": "running",
  "starttime": "2026-09-24T05:19:38",
  "configstatus": "configured",
  "version": "1.300073.0b1828"
}

Even if status is running and configstatus is configured, it does not necessarily mean the deployed configuration file has been applied.

Both Exit Code and Exception Are Required to Detect Failures

Failures detectable by exit code were: no configuration file (-1) and configuration value type error (1).
The JSON syntax error remained at 0.

Failures detectable by exception were: no configuration file and JSON syntax error.
No exception was raised for the configuration value type error.

To detect failures in a script, both the exit code and exceptions must be checked.

JSON Syntax Errors Pass fetch-config Validation but the Service Does Not Start

JSON syntax errors do not cause an error during fetch-config validation.

The config-translator (a subcommand of amazon-cloudwatch-agent.exe) that performs validation treats a configuration file it cannot read as "no configuration file" and passes validation using the default settings.

unable to scan config dir C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs with error: unable to parse json, error: invalid character '}' looking for beginning of object key string
No json config files found, use the default one
I! Valid Json input schema.
Configuration validation first phase succeeded

As a result, the exit code becomes 0, and the agent's configuration file (amazon-cloudwatch-agent.toml) is written with the default settings.

There is a GitHub Issue reporting this behavior—where default settings are used when JSON is invalid—for Linux.

https://github.com/aws/amazon-cloudwatch-agent/issues/966

On the other hand, at service startup, start-amazon-cloudwatch-agent.exe, which is registered as the service, validates the configuration file in the Configs folder once more. This validation fails on the same invalid JSON, and the service does not start.

unable to scan config dir C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs with error: unable to parse json, error: invalid character '}' looking for beginning of object key string
E! config-translator process exited with non-zero status: 99

The exception raised by fetch-config is due to this startup failure. Validation passes successfully, and the failure occurs during the subsequent service startup.

How to Determine Application Result

Determine by the file names in the C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs folder.

Get-ChildItem 'C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs'

However, in the case of a JSON syntax error, the invalid configuration file is imported as-is as file_amazon-cloudwatch-agent.json, so it cannot be distinguished by filename alone.
For this pattern, determine by the exception from fetch-config and the fact that status is stopped.

When incorporating into a script, use a three-stage check: exception, exit code, and Configs folder.

$ctl = 'C:\Program Files\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent-ctl.ps1'
$cfg = 'C:\ProgramData\Amazon\AmazonCloudWatchAgent\amazon-cloudwatch-agent.json'

# 1. Exception (no configuration file, JSON syntax error)
try {
  & $ctl -a fetch-config -m ec2 -c "file:$cfg" -s
} catch {
  throw "fetch-config failed: $($_.Exception.Message)"
}

# 2. Exit code (configuration value type error)
if ($LASTEXITCODE -ne 0) {
  throw "fetch-config failed with exit code $LASTEXITCODE"
}

# 3. Configs folder (check if running with default settings)
$applied = Get-ChildItem 'C:\ProgramData\Amazon\AmazonCloudWatchAgent\Configs' -Name
if ($applied -notcontains 'file_amazon-cloudwatch-agent.json') {
  throw "config not applied. Configs: $($applied -join ', ')"
}

By including this check in your user data or SSM Run Command script, the script will exit with an error when application fails, making the failure visible in the execution results.

Summary

I confirmed the behavior when configuration application fails for the CloudWatch Agent on Windows.

• status returns running / configured — the same as when a correct configuration file is applied — even when running with default settings
• Depending on the type of failure, the exit code varies between -1 / 0 / 1, and exceptions may or may not be raised
• JSON syntax errors pass fetch-config validation and fail at re-validation during service startup
• The Configs folder filename can distinguish between default settings (default) and the deployed configuration file (file_amazon-cloudwatch-agent.json)

Since status alone cannot confirm whether the configuration has been applied, automation requires a three-stage check using exception, exit code, and the Configs folder.

I hope this article is helpful to someone. Thank you for reading to the end!

References

https://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/monitoring/start-CloudWatch-Agent-EC2-commandline-fleet.html

https://docs.aws.amazon.com/ja_jp/AmazonCloudWatch/latest/monitoring/troubleshooting-CloudWatch-Agent.html

https://github.com/aws/amazon-cloudwatch-agent/issues/966

https://github.com/aws/amazon-cloudwatch-agent