hashicorp/terraform · error

Error creating workspace %s: %v

Error message

Error creating workspace %s: %v

What it means

Thrown by StateMgr() after Workspaces.Read returned ErrResourceNotFound and the subsequent Workspaces.Create() call also failed. The remote backend auto-creates a workspace when one doesn't exist, so this error means the creation step was rejected — most often a permissions or naming problem rather than a network issue.

Source

Thrown at internal/backend/remote/backend.go:687

	workspace, err := b.client.Workspaces.Read(context.Background(), b.organization, name)
	if err != nil && err != tfe.ErrResourceNotFound {
		return nil, diags.Append(fmt.Errorf("Failed to retrieve workspace %s: %v", name, err))
	}

	if err == tfe.ErrResourceNotFound {
		options := tfe.WorkspaceCreateOptions{
			Name: tfe.String(name),
		}

		// We only set the Terraform Version for the new workspace if this is
		// a release candidate or a final release.
		if tfversion.Prerelease == "" || strings.HasPrefix(tfversion.Prerelease, "rc") {
			options.TerraformVersion = tfe.String(tfversion.String())
		}

		workspace, err = b.client.Workspaces.Create(context.Background(), b.organization, options)
		if err != nil {
			return nil, diags.Append(fmt.Errorf("Error creating workspace %s: %v", name, err))
		}
	}

	// This is a fallback error check. Most code paths should use other
	// mechanisms to check the version, then set the ignoreVersionConflict
	// field to true. This check is only in place to ensure that we don't
	// accidentally upgrade state with a new code path, and the version check
	// logic is coarser and simpler.
	if !b.ignoreVersionConflict {
		wsv := workspace.TerraformVersion
		// Explicitly ignore the pseudo-version "latest" here, as it will cause
		// plan and apply to always fail.
		if wsv != tfversion.String() && wsv != "latest" {
			return nil, diags.Append(fmt.Errorf("Remote workspace Terraform version %q does not match local Terraform version %q", workspace.TerraformVersion, tfversion.String()))
		}
	}

	client := &remoteClient{

View on GitHub (pinned to c9def3e214)

Solutions

1. Grant the API token's team permission to create workspaces (or admin access) in the org/team settings.
2. Pre-create the workspace manually in the HCP/TFE UI so StateMgr's Read succeeds and Create is never called.
3. Inspect the derived workspace name (prefix + local name) and ensure it uses only lowercase letters, digits, hyphens, underscores.
4. Check the wrapped %v for a quota/409/403 status and resolve accordingly (upgrade plan, pick a different name).

Example fix

// before - token without create rights triggers this on first run
// after - pre-create the workspace, or grant the team
//         'Create Workspaces' permission in HCP Terraform
$ terraform workspace new prod   # OR create via UI:
#   https://app.terraform.io/app/<org>/workspaces/new

// Pre-create the workspace so StateMgr's Create branch is never hit.
func ensureWorkspace(ctx context.Context, c *tfe.Client, org, name string) error {
    if _, err := c.Workspaces.Read(ctx, org, name); err == nil {
        return nil
    } else if !errors.Is(err, tfe.ErrResourceNotFound) {
        return err
    }
    _, err := c.Workspaces.Create(ctx, org, tfe.WorkspaceCreateOptions{Name: tfe.String(name)})
    return err
}

func isCreatePermitted(w *tfe.Workspace) bool {
    return w != nil && w.Permissions != nil && w.Permissions.CanUpdate
}

ws, err := b.client.Workspaces.Create(ctx, org, opts)
if err != nil {
    if errors.Is(err, context.Canceled) {
        return err
    }
    return fmt.Errorf("Error creating workspace %s: %w", name, err)
}

When it happens

Trigger: StateMgr() reaches the Create branch (workspace missing) and b.client.Workspaces.Create() returns an error: token lacks workspace-create permission, the derived name contains invalid characters, a name-collision race happened, or the organization hit its workspace quota.

Common situations: Using a read-only or member token instead of a team token with 'Create Workspaces' / admin rights; workspace name resolves to something with spaces, uppercase letters, or special chars due to a `prefix` mismatch; exceeding the org's plan workspace limit on HCP Terraform.

Related errors

• Failed to retrieve workspace %s: %v
• error deleting workspace %s: %w
• Remote workspace Terraform version %q does not match local T
• workspace %s not found The configured "remote" backend retu
• error finding remote workspace: %w

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