hashicorp/terraform · error

error snapshotting Blob %q (Container %q / Account %q): %+v

Error message

error snapshotting Blob %q (Container %q / Account %q): %+v

What it means

Raised in RemoteClient.Put (client.go:97-103) when the backend's snapshot feature is enabled (snapshot = true / ARM_SNAPSHOT=true). Before overwriting the state blob, Terraform snapshots the existing blob for point-in-time recovery; if the Giovanni Snapshot data-plane call fails, this error (with key/container/account context) is returned and the state write aborts to avoid losing the snapshot trail.

Source

Thrown at internal/backend/remote-state/azure/client.go:102

	setOptions := blobs.SetPropertiesInput{}
	putOptions := blobs.PutBlockBlobInput{}

	options := blobs.GetInput{}
	if c.leaseID != "" {
		options.LeaseID = &c.leaseID
		getOptions.LeaseID = &c.leaseID
		setOptions.LeaseID = &c.leaseID
		putOptions.LeaseID = &c.leaseID
	}

	ctx := newCtx()

	if c.snapshot {
		snapshotInput := blobs.SnapshotInput{LeaseID: options.LeaseID}

		log.Printf("[DEBUG] Snapshotting existing Blob %q (Container %q / Account %q)", c.keyName, c.containerName, c.accountName)
		if _, err := c.giovanniBlobClient.Snapshot(ctx, c.containerName, c.keyName, snapshotInput); err != nil {
			return diags.Append(fmt.Errorf("error snapshotting Blob %q (Container %q / Account %q): %+v", c.keyName, c.containerName, c.accountName, err))
		}

		log.Print("[DEBUG] Created blob snapshot")
	}

	blob, err := c.giovanniBlobClient.GetProperties(ctx, c.containerName, c.keyName, getOptions)
	if err != nil {
		if !response.WasNotFound(blob.HttpResponse) {
			return diags.Append(err)
		}
	}

	contentType := "application/json"
	putOptions.Content = &data
	putOptions.ContentType = &contentType
	putOptions.MetaData = blob.MetaData
	_, err = c.giovanniBlobClient.PutBlockBlob(ctx, c.containerName, c.keyName, putOptions)

View on GitHub (pinned to c9def3e214)

Solutions

1. Ensure no other process holds a lease on the state blob during apply
2. Confirm the credential has 'Storage Blob Data Contributor' (data-plane) permission
3. Retry — transient storage errors often resolve on the next run
4. If snapshots are unsupported by your account tier/replication, set snapshot = false

Example fix

# before: snapshot enabled but write fails under contention
terraform {
  backend "azurerm" {
    storage_account_name = "mystage"
    snapshot             = true
    ...
  }
}

# after: disable snapshot if unsupported, or serialize runs
terraform {
  backend "azurerm" {
    storage_account_name = "mystage"
    snapshot             = false
    ...
  }
}
# ensure only one terraform apply runs at a time per workspace

# Confirm the state blob is not lease-locked before an apply with snapshot=true
STATUS=$(az storage blob show --account-name "$ARM_STORAGE_ACCOUNT_NAME" -c "$ARM_CONTAINER_NAME" -n "$ARM_KEY" --query 'properties.lease.status' -o tsv 2>/dev/null)
[ "$STATUS" = "locked" ] && echo "WARN: blob locked -> snapshot may fail (153)" || echo "OK: writable"

# Retry transient snapshot failures with bounded backoff
apply_with_snapshot() {
  for attempt in 1 2 3; do
    if terraform apply -auto-approve; then return 0; fi
    grep -q "error snapshotting Blob" && sleep $((attempt*5)) || return 1
  done
  echo "snapshot keeps failing; consider snapshot=false or serialize runs"
  return 1
}

When it happens

Trigger: Produced at client.go:101-103 when c.snapshot is true and c.giovanniBlobClient.Snapshot(ctx, containerName, keyName, snapshotInput) returns an error during a state write (terraform apply/refresh that persists state).

Common situations: The blob is lease-locked by another process so Snapshot cannot proceed; the storage account/replication does not support snapshots; the blob was deleted between GetProperties and Snapshot; data-plane permission lacks 'create' for snapshot; transient storage service error.

Related errors

• retrieving key for Storage Account %q: %s
• new container client: %v
• retrieving container client: %v
• listing blobs: %v
• failed to lock azure state: %s

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/750c91c43dec6138. Report an issue: GitHub.