---
title: Troubleshoot data stream lifecycle transitions
description: Diagnose and resolve data stream backing indices that are not converting to frozen {{search-snaps}}.
url: https://www.elastic.co/elastic/docs-builder/docs/4572/troubleshoot/elasticsearch/data-stream-frozen-transition
products:
  - Elastic Documentation
  - Elasticsearch
applies_to:
  - Elastic Cloud Serverless: Unavailable
  - Elastic Stack: Generally available since 9.5
---

# Troubleshoot data stream lifecycle transitions
If the data stream lifecycle has frozen phase transitions turned on, older backing indices convert to [frozen searchable snapshots](https://www.elastic.co/elastic/docs-builder/docs/4572/manage-data/lifecycle/data-stream/dlm-searchable-snapshots) instead of staying on hot or warm nodes.
Until the conversion finishes, those indices keep using local storage.
Use the following troubleshooting information to diagnose problems with these transitions.

## Symptoms

- The [explain data lifecycle API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-explain-data-lifecycle) reports a conversion error on a backing index.
- <applies-to>Elastic Stack: Planned</applies-to> The `dlm_frozen_transitions` indicator of the [health report API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-health-report) is `yellow` or `unknown`.
- Backing indices older than the `frozen_after` lifecycle setting remain on non-frozen tiers.


## Diagnosis

Inspect the backing index with the [explain data lifecycle API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-indices-explain-data-lifecycle).
For example:
```json
```

If a backing index reports an `error`, that entry is the failure from the most recent recorded attempt.
Elasticsearch keeps retrying the conversion until you fix the cause.
`error.message` replaces any earlier message.
When the same failure is recorded again, `retry_count` increases.
A later attempt skips conversion steps that already finished and continues from the step that failed.

### Check frozen transition health

<applies-to>
  - Elastic Stack: Planned
</applies-to>

Use the [health report API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-health-report) to view overdue frozen conversions across the cluster:
```json
```

Example response:
```json
{
  "cluster_name": "my-cluster",
  "indicators": {
    "dlm_frozen_transitions": {
      "status": "yellow",
      "symptom": "An issue affecting DLM frozen-tier transitions was detected",
      "details": {
        "overdue_indices_count_by_state": {
          "unmarked": 1
        },
        "default_repository_configured": true,
        "overdue_indices_sample": [
          {
            "index_name": ".ds-my-data-stream-test-2026.10.17-000001",
            "transition_state": "unmarked"
          }
        ],
        "service_running": true,
        "overdue_indices_count": 1,
        "transitions_enabled": true
      },
      "impacts": [
        {
          "id": "elasticsearch:health:dlm_frozen_transitions:impact:frozen_transition_blocked",
          "severity": 3,
          "description": "Data stream backing indices may be delayed or blocked from transitioning to the frozen tier. Storage size and cost management could be impacted.",
          "impact_areas": [
            "deployment_management"
          ]
        }
      ],
      "diagnosis": [
        {
          "id": "elasticsearch:health:dlm_frozen_transitions:diagnosis:eligible_indices_unmarked",
          "cause": "Some indices are eligible for conversion to the frozen tier but have not been marked for conversion, even though a default snapshot repository is configured. 1 index is affected.",
          "action": "Check the current master node's logs for errors related to the data stream lifecycle and the DLM frozen transition service.",
          "help_url": "https://ela.st/health-dlm-frozen-transitions",
          "affected_resources": {
            "indices": [
              ".ds-my-data-stream-test-2026.10.17-000001"
            ]
          }
        }
      ]
    }
  }
}
```

Read the `status`, `symptom`, and each `diagnosis.action`.
In `details`, check `transitions_enabled`, `default_repository_configured`, and `overdue_indices_count_by_state` (`unmarked`, `marked`, or `queued`).
A conversion that is already running is not overdue, so the indicator stays `green` while that work is in progress.
- `green`: No overdue conversions or every overdue conversion is already running.
- `yellow`: Conversions are blocked, queued, or waiting while frozen transitions are turned off.
- `unknown`: The master node has not published health information for three [`dlm.frozen_transitions.health.publish_interval`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4572/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings#dlm-frozen-transition-health-publish-interval) intervals.

An index is overdue only after it has been past the `frozen_after` setting for longer than [`dlm.frozen_transitions.health.stuck_threshold`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4572/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings#dlm-frozen-transition-health-stuck-threshold).

## Resolution

Use the option that matches the error or diagnosis.
<applies-to>Elastic Stack: Planned</applies-to> When the health report is `yellow`, follow `diagnosis.action`.
1. If the error or diagnosis reports a missing default snapshot repository, register one. Refer to [Manage snapshot repositories](https://www.elastic.co/elastic/docs-builder/docs/4572/deploy-manage/tools/snapshot-and-restore/manage-snapshot-repositories).
2. If the error reports a license compliance failure, renew the license. Refer to [Elasticsearch pricing and subscriptions](https://www.elastic.co/subscriptions).
3. If frozen transitions are turned off, set [`dlm.frozen_transitions.enabled`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4572/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings#dlm-frozen-transition-enabled) to `true`. Transitions that are already running continue either way. Indices that are marked or queued stay overdue until you turn on the setting:
   ```json

   {
     "persistent": {
       "dlm.frozen_transitions.enabled": true
     }
   }
   ```
4. If the diagnosis reports queued transitions, inspect the `dlm_frozen_transition` thread pool with the [cat thread pool API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-cat-thread-pool):
   ```json
   ```
   A persistently full queue means conversions complete more slowly than indices become eligible. Wait for in-flight work to drain or add capacity so more conversions can run at once.
5. If the diagnosis reports that the frozen transition service is not running on the current master node, check that node's logs for frozen transition errors. Restart the master node if the service stays down.
6. <applies-to>Elastic Stack: Planned</applies-to> If the health indicator is `unknown`, check the current master node's logs and confirm the master is publishing frozen transition health on the [`dlm.frozen_transitions.health.publish_interval`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4572/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings#dlm-frozen-transition-health-publish-interval) schedule.


## Resources

- [Searchable snapshots for data streams](https://www.elastic.co/elastic/docs-builder/docs/4572/manage-data/lifecycle/data-stream/dlm-searchable-snapshots)
- [Data stream lifecycle](https://www.elastic.co/elastic/docs-builder/docs/4572/manage-data/lifecycle/data-stream)
- [Manage snapshot repositories](https://www.elastic.co/elastic/docs-builder/docs/4572/deploy-manage/tools/snapshot-and-restore/manage-snapshot-repositories)
- [Frozen tier transition settings](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4572/reference/elasticsearch/configuration-reference/data-stream-lifecycle-settings#_frozen_tier_transition_settings)