How to fix Error: Error creating Cosmos DB: OfferReplacePending in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 31, 2025· 99 views

The OfferReplacePending error occurs when Terraform tries to change Cosmos DB throughput (RU/s) while a previous scaling operation is still in progress. Azure only allows one throughput change at a time per container or database. Resolve this by waiting for pending operations or restructuring your Terraform configuration to apply changes sequentially.

Quick fix

Fixes OfferReplacePending

# Get Cosmos DB account details
az cosmosdb database show --resource-group <RG> --account-name <account-name> --name <database-name>

# Check for offer replacement status
az cosmosdb sql database throughput show --resource-group <RG> --account-name <account-name> --database-name <database-name>
  1. Check for pending offer replacement operations
  2. Wait for pending operations to complete
  3. Restructure Terraform to apply Cosmos DB changes sequentially
  4. Use terraform apply with reduced parallelism
terraform — error
# Get Cosmos DB account details
az cosmosdb database show --resource-group <RG> --account-name <account-name> --name <database-name>
# Check for offer replacement status
az cosmosdb sql database throughput show --resource-group <RG> --account-name <account-name> --database-name <database-name>
Error: Error creating Cosmos DB: OfferReplacePending

What this error means

Azure Cosmos DB throughput scaling operations (changing RU/s) can take significant time to complete, especially when scaling up requires adding new physical partitions to your database. When an `offerReplacePending` operation is in progress, Azure temporarily blocks new throughput change requests. When Terraform attempts to create or modify a Cosmos DB resource while a throughput change is pending, the Azure API returns an error indicating that an offer replacement operation is already in progress. This is a safeguard to prevent conflicting or overlapping scaling operations that could corrupt the database state. The error typically manifests as: - `OfferReplacePending` when checking the offer status - HTTP 423 (Locked) response from the Azure API - Terraform apply failure with the message "OfferReplacePending"

Typical symptoms

  • Terraform apply fails with 'OfferReplacePending' error when creating or updating Cosmos DB containers
  • The error occurs intermittently, especially when applying multiple Cosmos DB resources in parallel
  • Retrying the same Terraform apply succeeds after waiting a few minutes
  • The error mentions that another scaling operation is in progress
  • Manual operations in Azure Portal work fine, but Terraform consistently fails

Common causes

  1. A previous Cosmos DB throughput scaling operation (RU/s change) hasn't completed yet, and Terraform is trying to apply a new change
  2. Terraform is attempting to create multiple Cosmos DB containers or databases in parallel, and each is trying to modify throughput simultaneously
  3. You recently changed autoscale settings or manual throughput settings outside of Terraform, and Azure is still processing that change
  4. A large throughput increase is taking longer than expected to complete (can take 4-6 hours for significant scale-ups requiring physical partition splits)
  5. Your Terraform configuration includes multiple throughput modifications in a single apply, and Azure processes them sequentially, blocking subsequent changes

How to fix "Error: Error creating Cosmos DB: OfferReplacePending"

1Check for pending offer replacement operations

First, verify that there's actually a pending operation. You can check this in the Azure Portal:

1. Navigate to your Cosmos DB account
2. Go to Settings > Keys or Containers (depending on your resource type)
3. Look for any indication of ongoing scaling or throughput changes
4. Alternatively, use the Azure CLI:

bash
# Get Cosmos DB account details
az cosmosdb database show --resource-group <RG> --account-name <account-name> --name <database-name>

# Check for offer replacement status
az cosmosdb sql database throughput show --resource-group <RG> --account-name <account-name> --database-name <database-name>

If you see offerReplacePending: true or similar output, an operation is in progress.

2Wait for pending operations to complete

If a throughput scaling operation is pending, you must wait for it to finish before Terraform can apply new changes. Scaling duration depends on the size of the change:

- Small increases (within current partition capacity): Usually 30 seconds to a few minutes
- Large increases (requiring partition splits): Can take 4-6 hours

Do not interrupt the operation. Check the Activity Log in Azure Portal to monitor progress:

1. Go to your Cosmos DB account
2. Click Activity Log (usually in the left sidebar)
3. Look for entries like "Update Cosmos DB Throughput" or "Replace Offer"
4. Note the timestamp and estimated completion time

Once the operation completes, the offerReplacePending status will clear.

3Restructure Terraform to apply Cosmos DB changes sequentially

Prevent parallel apply operations by adding explicit dependencies in your Terraform configuration:

Instead of:

hcl
resource "azurerm_cosmosdb_sql_database" "main" {
  # ...
  throughput = 400
}

resource "azurerm_cosmosdb_sql_container" "container1" {
  # ...
  throughput = 400
}

resource "azurerm_cosmosdb_sql_container" "container2" {
  # ...
  throughput = 400
}

Use explicit depends_on to serialize changes:

hcl
resource "azurerm_cosmosdb_sql_database" "main" {
  # ...
  throughput = 400
}

resource "azurerm_cosmosdb_sql_container" "container1" {
  # ...
  throughput = 400
  depends_on = [azurerm_cosmosdb_sql_database.main]
}

resource "azurerm_cosmosdb_sql_container" "container2" {
  # ...
  throughput = 400
  depends_on = [azurerm_cosmosdb_sql_container.container1]
}

This ensures Terraform waits for each resource to fully provision before creating the next one.

4Use terraform apply with reduced parallelism

Limit how many resources Terraform creates simultaneously by using the -parallelism flag:

bash
terraform apply -parallelism=1

Setting parallelism to 1 forces Terraform to apply resources one at a time, completely avoiding concurrent throughput operations. This is slower but eliminates conflicts.

For a balance between speed and safety, you can use:

bash
terraform apply -parallelism=2

This creates up to 2 resources in parallel while still reducing conflicts.

5Separate database and container throughput provisioning

If you're changing throughput at both the database and container level, consider splitting this into two Terraform applies:

First, apply database-level changes:

hcl
resource "azurerm_cosmosdb_sql_database" "main" {
  # ... other config
  throughput = 1000  # Database-level throughput
}

Then, after the database scaling completes, apply container-level changes:

hcl
resource "azurerm_cosmosdb_sql_container" "example" {
  # ... other config
  throughput = 500  # Container-level throughput
}

You can automate this with a time-based delay:

hcl
resource "time_sleep" "wait_for_cosmosdb" {
  depends_on = [azurerm_cosmosdb_sql_database.main]
  create_duration = "5m"
}

resource "azurerm_cosmosdb_sql_container" "example" {
  # ...
  depends_on = [time_sleep.wait_for_cosmosdb]
}
6Retry Terraform apply after operation completes

Once pending operations finish, retry your Terraform deployment:

bash
terraform plan
terraform apply

If you continue to see OfferReplacePending errors, it may indicate:
1. Another operation just started (wait longer)
2. A bug in the Azure provider version (update it)
3. Conflicting manual changes (sync state with terraform refresh)

Update your Azure provider if it's outdated:

bash
terraform init -upgrade
terraform apply

If the issue persists, review the Azure Activity Log for any ongoing operations you may have missed.

Advanced notes

Understanding offer replacement pending: The offerReplacePending flag in Cosmos DB's internal state indicates that a PUT request to the offer resource has been received but not yet fully processed. Azure needs to validate the change, check partition limits, and potentially rebalance physical partitions. During this time, subsequent modifications are blocked.

Scaling time expectations: Small throughput increases (e.g., 400 RU/s to 500 RU/s) complete quickly. However, if your new throughput requirement exceeds what your current physical partition layout can support, Azure must split partitions, which can take 4-6 hours or longer depending on data volume and complexity.

Autoscale vs. Manual throughput: If using autoscale, Azure automatically manages throughput scaling based on demand. Mixing manual Terraform changes with autoscale can cause unexpected pending operations. Consider using either pure autoscale (managed by Azure) or pure manual (managed by Terraform), not both.

Terraform provider version: Older versions of the Azure provider (azurerm) may not handle OfferReplacePending gracefully. Update to the latest version to get better retry logic and error handling:

bash
terraform init -upgrade

State management: Ensure your Terraform state is stored in a remote backend (Azure Storage, Terraform Cloud, etc.). If your state is lost or corrupted, Terraform may try to re-create resources, triggering additional OfferReplacePending operations.

Frequently asked questions

What does "OfferReplacePending" mean?
Azure Cosmos DB throughput scaling operations (changing RU/s) can take significant time to complete, especially when scaling up requires adding new physical partitions to your database. When an offerReplacePending operation is in progress, Azure temporarily blocks new throughput change requests. When Terraform attempts to create or modify a Cosmos DB resource while a throughput change is pending, the Azure API returns an error indicating that an offer replacement operation is already in progress.
How do I fix "OfferReplacePending"?
The OfferReplacePending error occurs when Terraform tries to change Cosmos DB throughput (RU/s) while a previous scaling operation is still in progress. Azure only allows one throughput change at a time per container or database. Resolve this by waiting for pending operations or restructuring your Terraform configuration to apply changes sequentially.
What causes "OfferReplacePending"?
A previous Cosmos DB throughput scaling operation (RU/s change) hasn't completed yet, and Terraform is trying to apply a new change Terraform is attempting to create multiple Cosmos DB containers or databases in parallel, and each is trying to modify throughput simultaneously You recently changed autoscale settings or manual throughput settings outside of Terraform, and Azure is still processing that change
Is the "OfferReplacePending" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading