How to fix Error: keepers value has changed in Terraform

TerraformINTERMEDIATEHIGHUpdated Dec 31, 2025· 139 views

The "keepers value has changed" error occurs when a random resource's keeper values are modified between Terraform plan and apply phases. This causes Terraform to detect inconsistency and fail. Understanding when and why keepers change is critical for reliable infrastructure code.

Quick fix

Fixes Error: keepers value has changed

resource "random_id" "instance" {
  keepers = {
    ami_id = var.ami_id  # Input variable, stable across plan/apply
  }
  byte_length = 8
}
  1. Verify your keepers reference stable, pre-existing values
  2. Remove dynamic or computed values from keepers
  3. Break circular dependencies by restructuring resources
  4. Use depends_on for resource ordering when needed
terraform — error
resource "random_id" "instance" {
  keepers = {
    ami_id = var.ami_id  # Input variable, stable across plan/apply
  }
  byte_length = 8
}
Error: keepers value has changed

What this error means

In Terraform's random provider, the `keepers` argument is a map of arbitrary key-value pairs used to control when a random value should be regenerated. By design, random values are deterministic—once generated, they remain the same across multiple terraform plan and apply cycles unless the keepers themselves change. When you see "keepers value has changed," it means the keeper values that Terraform recorded during the plan phase differ from their values during the apply phase. This creates an inconsistency because the random resource was told to keep its value stable based on certain conditions, but those conditions changed mid-execution. This error typically indicates one of three problems: (1) keeper values are dynamic and change between plan and apply, (2) there's a circular dependency preventing proper evaluation order, or (3) referenced values in keepers haven't been computed yet when Terraform tries to use them.

Typical symptoms

  • terraform plan succeeds but terraform apply fails with 'keepers value has changed'
  • Error includes message like 'Provider produced inconsistent final plan' or 'inconsistent result during apply'
  • The issue appears only during apply, not during plan phase
  • Error shows two different hash values for the same keeper in plan vs apply logs
  • Using random_id, random_string, random_pet, or random_password resources with keepers

Common causes

  1. Keeper values reference computed attributes from other resources created in the same apply run (file hashes, resource IDs, etc.) that change between plan and apply phases
  2. Keeper values contain interpolations that resolve to different values during plan vs apply (like filemd5() of generated files)
  3. Circular dependency where the random resource's keepers reference a resource that depends on the random resource's output
  4. Dynamic values in keepers that aren't fully resolved during the planning phase
  5. Using data source attributes in keepers that refresh or change during apply

How to fix "Error: keepers value has changed"

1Verify your keepers reference stable, pre-existing values

Examine the keepers block in your random resource configuration. Keepers should only reference values that exist before Terraform starts the apply phase and won't change afterward.

Good example—reference a pre-existing input variable:

hcl
resource "random_id" "instance" {
  keepers = {
    ami_id = var.ami_id  # Input variable, stable across plan/apply
  }
  byte_length = 8
}

Bad example—reference a computed resource attribute:

hcl
resource "random_id" "instance" {
  keepers = {
    file_hash = filemd5("./config.txt")  # May differ between plan and apply
  }
  byte_length = 8
}

Identify any keepers that reference computed outputs, file operations, or attributes of resources created in the same run.

2Remove dynamic or computed values from keepers

Replace any computed keeper values with stable references. If you need to regenerate a random value based on a resource's attribute, use depends_on instead.

Replace file hashes with static content if possible:

hcl
# Bad: file hash changes during apply
keepers = {
  config_hash = filemd5("./config.txt")
}

# Better: reference a static input variable
keepers = {
  config_version = var.config_version
}

After editing keepers, run:

bash
terraform plan

The plan should now show consistent keeper values without proposing replacement.

3Break circular dependencies by restructuring resources

If the error persists, check for circular references where:
1. Random resource's keepers reference ResourceA
2. ResourceA depends on the random resource's output

This creates a cycle that Terraform can't resolve. Fix it by restructuring your configuration.

Example of a circular dependency:

hcl
# WRONG: Circular dependency
resource "random_id" "bucket_id" {
  keepers = {
    bucket_name = aws_s3_bucket.my_bucket.id  # Depends on S3 bucket
  }
}

resource "aws_s3_bucket" "my_bucket" {
  bucket = "my-bucket-${random_id.bucket_id.hex}"  # Depends on random_id
}

Fix it by breaking the cycle:

hcl
# CORRECT: No circular dependency
resource "random_id" "bucket_id" {
  keepers = {
    prefix = var.bucket_prefix  # Reference input variable only
  }
  byte_length = 8
}

resource "aws_s3_bucket" "my_bucket" {
  bucket = "${var.bucket_prefix}-${random_id.bucket_id.hex}"
}

Re-run terraform plan to confirm the cycle is resolved.

4Use depends_on for resource ordering when needed

If you need the random value to regenerate when another resource changes, use depends_on instead of adding that resource's attributes to keepers.

Good practice:

hcl
resource "random_id" "new_id" {
  keepers = {
    # Only reference stable values
    seed = var.regenerate_seed
  }
  depends_on = [
    aws_instance.app  # Ensures proper ordering
  ]
  byte_length = 8
}

This tells Terraform to respect the dependency without creating inconsistency in keeper values.

5Trigger replacement on demand if you need a new value

If you genuinely need a new random value, don't try to force it through changing keepers. Instead, use the replace option:

bash
terraform apply -replace=random_id.bucket_id

This explicitly tells Terraform to destroy and recreate that resource, generating a new random value. This is safer and clearer than trying to manipulate keepers.

Alternatively, you can change a keeper variable manually:

bash
terraform apply -var="regenerate_seed=2"

This changes the keeper value uniformly during apply, avoiding inconsistency errors.

6Check Terraform version and update if necessary

This issue has been partially addressed in newer versions of Terraform and the random provider. Ensure you're running a recent version:

bash
terraform version

Update to the latest Terraform and random provider:

bash
terraform init -upgrade

Check your .terraform/versions or terraform.lock.hcl to see which version of the random provider you're using. Consider upgrading to the latest:

hcl
terraform {
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.5"  # Use latest stable version
    }
  }
}

After upgrading, run terraform init and test again.

Advanced notes

Understanding keeper behavior is essential for predictable infrastructure code. Keepers were designed to give you deterministic control over when random values regenerate—they're a feature, not a bug. The error occurs when Terraform detects that your keeper conditions changed mid-execution, which undermines that predictability.

In production environments, prefer changing keepers through variables passed at apply time rather than through computed resource attributes. This ensures consistency and makes the regeneration explicit and auditable.

For complex scenarios involving file generation, consider using local_file resources in a separate terraform apply step, then reference their hashes in subsequent runs. Alternatively, use external data sources to fetch stable values that can be used in keepers.

When troubleshooting, always check your terraform.lock.hcl to ensure you're using compatible versions of the random provider and Terraform core—version mismatches can sometimes cause consistency issues.

Frequently asked questions

What does "Error: keepers value has changed" mean?
In Terraform's random provider, the keepers argument is a map of arbitrary key-value pairs used to control when a random value should be regenerated. By design, random values are deterministic—once generated, they remain the same across multiple terraform plan and apply cycles unless the keepers themselves change. When you see "keepers value has changed," it means the keeper values that Terraform recorded during the plan phase differ from their values during the apply phase.
How do I fix "Error: keepers value has changed"?
The "keepers value has changed" error occurs when a random resource's keeper values are modified between Terraform plan and apply phases. This causes Terraform to detect inconsistency and fail. Understanding when and why keepers change is critical for reliable infrastructure code.
What causes "Error: keepers value has changed"?
Keeper values reference computed attributes from other resources created in the same apply run (file hashes, resource IDs, etc.) that change between plan and apply phases Keeper values contain interpolations that resolve to different values during plan vs apply (like filemd5() of generated files) Circular dependency where the random resource's keepers reference a resource that depends on the random resource's output
Is the "Error: keepers value has changed" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading