Preventing Automatic Workspace Creation in HCP Terraform when using the "cloud" block

What is this article about and what problem does it solve?

This article explains how to prevent Terraform CLI from automatically creating a new workspace in HCP Terraform when the workspace defined in the cloud block does not already exist.

By default, when using:

terraform {
  cloud {
    organization = "my-org"

    workspaces {
      name = "example-workspace"
    }
  }
}

If example-workspace does not already exist in HCP Terraform, Terraform will automatically create it.

In some environments, this behavior is not desirable. This article describes how to configure Terraform so that it fails instead of creating a new workspace.

Why do we need to solve this problem?

This topic was raised after a customer observed that a workspace, which had not been pre-created, was automatically created in HCP Terraform. The workspace:

• Was placed in the default project

• Used the organization’s default execution mode

• Was created without explicit approval or intent

While this behavior is expected, it may not align with certain governance or operational requirements.

This should be considered in environments where:

• Workspaces must be pre-approved or centrally managed

• Workspace creation is restricted to specific teams

• Configurations are generated programmatically

• CI/CD pipelines should fail on misconfiguration

• Strict lifecycle control over workspaces is required

In these scenarios, automatic workspace creation can result in unintended workspace sprawl or governance concerns.

How do we solve the problem?

To prevent automatic workspace creation, avoid defining workspaces.name in the cloud block and instead use the TF_WORKSPACE environment variable.

1. Remove the workspaces block from the cloud block

Instead of:

workspaces {
  name = "example-workspace"
}

Use:

terraform {
  cloud {
    organization = "my-org"
  }
}

2. Set the workspace using TF_WORKSPACE environment variable 

Set the workspace via TF_WORKSPACE environment variable:

export TF_WORKSPACE="example-workspace"

Or in CI/CD pipelines:

TF_WORKSPACE=example-workspace terraform plan

Resulting behavior

• If the workspace exists, Terraform proceeds normally.

• If the workspace does not exist, Terraform fails.

$ TF_WORKSPACE=example-workspace terraform init
Initializing HCP Terraform...
╷
│ Error: Invalid workspace selection
│ 
│ Terraform failed to find workspace "example-workspace" in
│ organization my-org.

• No new workspace is created.

Behavior comparison

Using TF_WORKSPACE provides stricter control over workspace lifecycle and helps prevent unintended workspace creation.