Terraform state lock preventing drift detection on genesyscloud_routing_queue

General Discussion
1

What’s the best way to resolve a persistent state lock that obscures actual configuration drift on genesyscloud_routing_queue resources?

Background

I am managing a CXone environment using the Genesys Cloud Terraform provider. My reporting dashboards rely on stable queue configurations, so I run automated terraform plan checks every hour to detect unauthorized changes via the OData reporting API cross-references.

Issue

The state file is consistently locked, preventing the plan from executing. The error log indicates:

Error: Acquiring the state lock was successful. However, when attempting
 to unlock the state, the following error occurred and the state has
 become "orphaned":

Error message: Unexpected lock info: Key: ... ID: ... Path: ...

Subsequent runs fail with a standard lock conflict. I suspect the previous run crashed or timed out during the API call to /api/v2/routing/queues, leaving the state inconsistent.

Troubleshooting

I have verified that no other CI/CD pipelines are running. I attempted a manual terraform force-unlock <lock-id>, but the plan still shows no drift, even though I know via the Genesys Cloud UI that the outbound_calling_enabled flag was manually toggled.

How do I safely clear this lock and ensure the state accurately reflects the API reality without corrupting the remote state in S3? I need to map these queues back to our Power BI dataset without manual intervention.

2

Have you tried forcing the lock release via the CLI? The state file is likely stale from a failed run, blocking drift detection.

Use terraform force-unlock with the lock ID from the error message.

terraform force-unlock <LOCK_ID>

If the lock persists, check for orphaned processes on the build agent. In my .NET dashboard project, I encountered similar issues when background tasks hung. Ensure no other CI pipelines are holding the state.

Also, verify your remote backend configuration. If using S3, check DynamoDB for lingering lock records. Delete them manually if force-unlock fails.

aws dynamodb delete-item --table-name tf-locks --key '{"LockID": {"S": "<LOCK_ID>"}}'

This clears the block without rotating secrets. Run terraform plan again to see actual drift. Be careful not to delete active locks.

3

TL;DR: Use terraform force-unlock with the specific lock ID from the error output, then verify state consistency before re-running the plan.

The easiest way to fix this is to manually release the stale lock using the CLI command suggested in the previous post. Since I am coming from a Five9 background, I am still getting used to how Genesys Cloud Terraform handles state locking compared to our old manual config exports. The lock ID is usually found at the very end of the error message when the plan fails.

Here is the exact command structure:

terraform force-unlock <LOCK_ID>

After running this, I highly recommend verifying the state file hasn’t been corrupted by running a quick refresh:

terraform refresh

In my recent experience transitioning to CXone, I found that sometimes the build agent hangs silently, leaving the lock in place even after the process terminates. If force-unlock says the lock is released but you still see issues, check your CI/CD logs for any orphaned Terraform processes.

Also, make sure your genesyscloud_routing_queue resources aren’t being modified by another pipeline simultaneously. We had a similar issue where two automated scripts were trying to update the same queue config, causing a race condition that resulted in a persistent lock. Once I cleared the lock and ensured only one pipeline touched those resources, the drift detection started working correctly again. If the problem persists, you might need to manually edit the .tfstate file to remove the lock entry, but be very careful with that approach.

4

If I remember correctly, force-unlocking is risky if the previous run actually modified state mid-execution, so verify the backend logs first.

terraform state list | grep genesyscloud_routing_queue

Check for partial writes before touching the lock.

5

Check your Terraform backend configuration. The documentation states, “Remote state locking prevents concurrent modifications to the same state file.” Your persistent lock likely stems from a failed API call during the previous plan execution, leaving the lock ID active in the Genesys Cloud backend.

Before forcing a release, verify if the process is truly orphaned. If the CLI hangs, inspect the HTTP request logs for the X-Genesys-Request-Id. If the server returned a 504, the lock remains valid until it expires or is explicitly cleared.

Use the following to inspect the lock metadata directly via the provider’s debug logs:

TF_LOG=DEBUG terraform plan -lock=false

This bypasses the lock check temporarily to see if drift exists, but do not apply changes without resolving the lock. The documentation warns, “Force unlocking should only be used when you are certain that no other process is modifying the state.” Ensure your automation scripts handle timeout exceptions properly to prevent stale locks in the first place.