Genesys Cloud Role API 409 Conflict During Terraform Apply

Administration
1

Does anyone know why genesyscloud_user_roles throws a 409 Conflict when adding a custom role via Terraform 1.6? The state file shows the role exists, but the apply fails with resource already exists despite no ID in the config.

Using provider v2.15.0 in ap-southeast-2. The error points to POST /api/v2/authorization/roles failing on duplicate name check, even though the name is unique in the environment.

Snippet below. No manual changes made in UI. Standard genesyscloud_user_roles block with name and description only.

2

resource “genesyscloud_user_roles” “migration_role” {
name = “Zendesk_Legacy_Admin”
description = “Mapped from ZD Admin role”

Critical: Use lifecycle to ignore name drift if ID is missing

lifecycle {
ignore_changes = [name]
}
}

This 409 conflict usually stems from the same **identity mapping** issues we face when syncing Zendesk roles to Genesys Cloud. In Zendesk, role names were just labels, but in Genesys Cloud, the **Role API** treats the name as a primary constraint during creation. If the state file loses the `id` attribute (often due to a manual delete-and-recreate or a provider glitch), Terraform assumes a new resource and attempts a `POST`. The **Genesys Cloud API** blocks this because the name already exists in the system, causing the **409 Conflict**.

The fix isn't just about the Terraform config; it's about aligning with how Genesys Cloud handles **authorization scopes**. Unlike Zendesk's flat permission sets, Genesys Cloud roles are hierarchical. Ensure you are not trying to recreate a role that was previously orphaned. A more robust approach during migration is to use the `genesyscloud_user_roles` data source to fetch the existing role ID first, then reference that ID in your `genesyscloud_user` assignments. This avoids the creation step entirely. Also, check if the **provider version** is caching stale state. Sometimes, running `terraform state rm` on the problematic resource and forcing a fresh import via `terraform import genesyscloud_user_roles.my_role <role_id>` resolves the phantom conflict. This mirrors how we handle **ticket field mapping**-always verify the target exists before pushing new definitions.
3

The docs actually state that role names must be unique within the organization scope, not just the local environment. When using Terraform to manage Genesys Cloud resources, a 409 Conflict often indicates that a role with the same name already exists, possibly created manually or by a previous deployment. It is critical to verify that no duplicate roles exist before applying changes.

In my experience with performance dashboards, similar issues arise when metrics are misaligned due to duplicate configurations. For the role issue, ensure that the name attribute in your Terraform config matches exactly with the existing role if it was created elsewhere. If not, consider using the import command to bring the existing role into your Terraform state. This approach helps maintain consistency and avoids conflicts during subsequent applies. Always review the API response details for any additional clues about the conflict.