# How to Debug CloudWatch Alarm INSUFFICIENT_DATA States: A Complete Troubleshooting Guide

> Troubleshoot and resolve CloudWatch alarm INSUFFICIENT_DATA states. Learn common causes like namespace mismatches and missing metrics in this comprehensive guide.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: how-to-guide
- Published: 2026-06-26

---

**CloudWatch alarms enter the `INSUFFICIENT_DATA` state when they cannot evaluate the metric due to namespace mismatches, missing metric publication, or misconfigured `TreatMissingData` settings.**

Troubleshooting CloudWatch alarms stuck in `INSUFFICIENT_DATA` requires analyzing how metrics are published and how alarms evaluate datapoints. According to the `aws/agent-toolkit-for-aws` repository, this state typically indicates that CloudWatch cannot locate the expected metric data or that the evaluation window contains no valid datapoints. Understanding the root causes documented in [`skills/core-skills/aws-observability/references/troubleshooting.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-observability/references/troubleshooting.md) allows you to systematically resolve these issues.

## Understanding Why Alarms Enter INSUFFICIENT_DATA

CloudWatch alarms transition to `INSUFFICIENT_DATA` when the evaluation logic cannot find sufficient metric data to determine if the threshold has been breached. The `aws/agent-toolkit-for-aws` repository identifies four primary architectural reasons for this behavior.

### Namespace and Dimension Mismatches

A mismatch between the alarm configuration and the actual metric stream is the most common cause. CloudWatch metric namespaces are case-sensitive; an alarm configured for `AWS/Lambda` will not match metrics published to `aws/lambda`. Similarly, any deviation in `Dimensions` (such as `FunctionName` vs `functionName`) creates a complete disconnect where CloudWatch receives no data, immediately yielding `INSUFFICIENT_DATA`.

### Metric Publication Interruptions

If the target resource stops publishing metrics, the alarm has no datapoints to evaluate. This occurs when:
- Compute resources (EC2, Lambda, ECS) are terminated or stopped
- Application code stops calling `PutMetricData` or emitting Embedded Metric Format (EMF)
- Service-linked metrics are paused due to resource deletion

### Missing Data Treatment Configuration

The `TreatMissingData` setting determines how CloudWatch handles evaluation windows that contain no data. According to [`skills/core-skills/aws-observability/references/alarms.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-observability/references/alarms.md), the default value is `missing`, which treats empty windows as `INSUFFICIENT_DATA`. For intermittent metrics like error counters, this default often produces false `INSUFFICIENT_DATA` states when you actually want `notBreaching` (treat missing as OK) or `breaching` (treat missing as ALARM).

### Evaluation Window Timing

Alarms with short periods and sparse data require time to accumulate sufficient datapoints. If you create an alarm on a metric that publishes every 5 minutes but set the alarm period to 60 seconds, the alarm will remain in `INSUFFICIENT_DATA` until enough evaluation periods pass.

## Step-by-Step Debugging Workflow

Follow this systematic approach using the AWS CLI to diagnose and resolve `INSUFFICIENT_DATA` states.

### 1. Inspect the Alarm Configuration

Retrieve the complete alarm definition to verify namespace, dimensions, and missing data treatment:

```bash
aws cloudwatch describe-alarms --alarm-names MyAlarm --region $AWS_REGION

```

Review the output for `Namespace`, `MetricName`, `Dimensions`, and `TreatMissingData` fields.

### 2. Validate Metric Existence

Confirm that CloudWatch is actually receiving the metric stream:

```bash
aws cloudwatch list-metrics \
    --namespace AWS/Lambda \
    --metric-name Duration \
    --dimensions Name=FunctionName,Value=my-function \
    --region $AWS_REGION

```

If this returns an empty list, the resource is not publishing metrics, and the alarm will remain in `INSUFFICIENT_DATA` until publication resumes.

### 3. Check Recent Datapoint History

Verify whether data was recorded in the last evaluation window:

```bash
aws cloudwatch get-metric-statistics \
    --namespace AWS/Lambda \
    --metric-name Duration \
    --dimensions Name=FunctionName,Value=my-function \
    --statistics Average \
    --period 300 \
    --start-time $(date -u -d '-30 minutes' +%Y-%m-%dT%H:%M:%SZ) \
    --end-time $(date -u +%Y-%m-%dT%H:%M:%SZ) \
    --region $AWS_REGION

```

If `Datapoints` is empty, the metric stream is broken at the source.

### 4. Adjust TreatMissingData for Intermittent Metrics

For error-type metrics that only emit values during failures, configure the alarm to treat missing data as "not breaching":

```bash
aws cloudwatch put-metric-alarm \
    --alarm-name MyAlarm \
    --metric-name Errors \
    --namespace AWS/Lambda \
    --statistic Sum \
    --period 300 \
    --evaluation-periods 1 \
    --threshold 1 \
    --comparison-operator GreaterThanOrEqualToThreshold \
    --treat-missing-data notBreaching \
    --alarm-actions arn:aws:sns:us-east-1:123456789012:my-topic \
    --region $AWS_REGION

```

### 5. Force Alarm State for Testing

To verify notification flows without waiting for metric conditions, manually set the alarm state:

```bash
aws cloudwatch set-alarm-state \
    --alarm-name MyAlarm \
    --state-value ALARM \
    --state-reason "Testing notification flow"

```

## Special Considerations for Composite Alarms

**Composite alarms** inherit the `INSUFFICIENT_DATA` state from their constituent alarms. If a composite alarm shows `INSUFFICIENT_DATA`, you must debug and fix the underlying metric alarms first. Additionally, as documented in [`skills/core-skills/aws-observability/references/alarms.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-observability/references/alarms.md), Auto Scaling actions continue to fire while an alarm is stuck in `INSUFFICIENT_DATA` because they are not gated by state changes.

## Summary

- **Verify namespace case sensitivity**: Ensure `Namespace`, `MetricName`, and `Dimensions` match exactly between the alarm configuration and the published metric stream.
- **Check resource health**: Confirm the underlying resource is actively publishing metrics via `list-metrics` and `get-metric-statistics`.
- **Configure TreatMissingData**: Change from the default `missing` to `notBreaching` for intermittent metrics to prevent false `INSUFFICIENT_DATA` states.
- **Validate evaluation windows**: Ensure the alarm period covers the metric's publication frequency.
- **Check composite alarm sources**: Resolve child alarm issues before troubleshooting composite alarms.

## Frequently Asked Questions

### Why does my new CloudWatch alarm immediately show INSUFFICIENT_DATA?

Newly created alarms start in `INSUFFICIENT_DATA` until the first evaluation window completes. If your metric publishes every 5 minutes and you set `--evaluation-periods 2`, you must wait 10 minutes for the alarm to transition to `OK` or `ALARM`.

### What is the difference between notBreaching and breaching in TreatMissingData?

The `notBreaching` setting treats missing data as "healthy," keeping the alarm in `OK` state when no datapoints arrive. The `breaching` setting treats missing data as "unhealthy," transitioning the alarm to `ALARM` state. Use `notBreaching` for error metrics that only appear during failures; use `breaching` for critical availability metrics where silence indicates an outage.

### How do I fix an alarm stuck in INSUFFICIENT_DATA for a terminated EC2 instance?

First, verify the instance ID matches exactly using `aws cloudwatch list-metrics --namespace AWS/EC2 --dimensions Name=InstanceId,Value=i-1234567890abcdef0`. If the instance is terminated, the metric stream stops permanently. You must either update the alarm dimensions to a running instance or delete the alarm.

### Can Auto Scaling continue scaling while the alarm is in INSUFFICIENT_DATA?

Yes. According to the `aws/agent-toolkit-for-aws` source code, Auto Scaling actions are not gated by the `INSUFFICIENT_DATA` state. Scaling policies continue to evaluate and execute based on their own internal logic even when the triggering alarm cannot gather sufficient data.