Changing Stack Slugs: Understanding Cache Behavior

Last updated: September 9, 2025

When changing a Stack's slug through the GraphQL API rather than Terraform, you need to be aware of how Spacelift's caching behavior affects subsequent Terraform operations.

Important Considerations

If you change a Stack's slug outside of Terraform (e.g., via GraphQL API), the Terraform provider won't immediately recognize it as the same object. This is because the provider relies on Spacelift's object cache to identify existing resources.

Correct Process

To successfully change a Stack's slug and maintain Terraform state consistency, follow these steps:

  1. Make your slug changes via GraphQL API

  2. Trigger a tracked run on the affected Stack (this will refresh Spacelift's object cache)

  3. After the cache refresh, you can proceed with importing the Stack back into Terraform

Warning: Changing a Stack's slug can impact resources that reference the Stack by ID. Some resources may need to be recreated. Ensure you understand the implications before proceeding with slug changes.

Common Issues

If you attempt to import the Stack into Terraform immediately after changing its slug, the import may fail because the provider will attempt to create a new Stack instead. This happens because the object cache hasn't been refreshed yet. Always ensure you trigger a tracked run first to update the cache.