hashicorp/terraform · error

error creating workspace %s: %v

Error message

error creating workspace %s: %v

What it means

Returned in backend StateMgr at backend.go:810 when b.client.Workspaces.Create fails during workspace auto-creation for a cloud backend (the workspace does not exist and must be created before plan/apply can proceed). %s=workspace name, %v=the raw TFE API error.

Source

Thrown at internal/cloud/backend.go:810

				createOpts := tfe.ProjectCreateOptions{
					Name: b.WorkspaceMapping.Project,
				}
				// didn't find project, create it instead
				log.Printf("[TRACE] cloud: Creating %s project %s/%s", b.appName, b.Organization, b.WorkspaceMapping.Project)
				project, err := b.client.Projects.Create(context.Background(), b.Organization, createOpts)
				if err != nil && err != tfe.ErrResourceNotFound {
					return nil, diags.Append(fmt.Errorf("failed to create project %s: %v", b.WorkspaceMapping.Project, err))
				}
				configuredProject = project
				workspaceCreateOptions.Project = configuredProject
			}
		}

		// Create a workspace
		log.Printf("[TRACE] cloud: Creating %s workspace %s/%s", b.appName, b.Organization, name)
		workspace, err = b.client.Workspaces.Create(context.Background(), b.Organization, workspaceCreateOptions)
		if err != nil {
			return nil, diags.Append(fmt.Errorf("error creating workspace %s: %v", name, err))
		}

		remoteTFVersion = workspace.TerraformVersion

		// Attempt to set the new workspace to use this version of Terraform. This
		// can fail if there's no enabled tool_version whose name matches our
		// version string, but that's expected sometimes -- just warn and continue.
		versionOptions := tfe.WorkspaceUpdateOptions{
			TerraformVersion: tfe.String(tfversion.String()),
		}
		_, err := b.client.Workspaces.UpdateByID(context.Background(), workspace.ID, versionOptions)
		if err == nil {
			remoteTFVersion = tfversion.String()
		} else {
			// TODO: Ideally we could rely on the client to tell us what the actual
			// problem was, but we currently can't get enough context from the error
			// object to do a nicely formatted message, so we're just assuming the
			// issue was that the version wasn't available since that's probably what

View on GitHub (pinned to c9def3e214)

Solutions

1. Pre-create the workspace in the HCP/TFE UI and let Terraform select it.
2. Grant the token's team workspace-create (admin) permission on the org/project.
3. Resolve 409 conflicts (rename or pick an unused workspace name).
4. Check the workspace name for invalid characters and org quota limits.

Example fix

// before: workspace missing, token cannot create
cloud { organization = "acme" workspaces { name = "prod-app" } }

// after: pre-create workspace in UI, or grant admin token
cloud { organization = "acme" workspaces { name = "prod-app" } }
# create workspace 'prod-app' in HCP Terraform UI first, or use an admin token

// Pre-create the workspace (idempotent) before plan/apply.
func ensureWorkspace(c *tfe.Client, org, name string) error {
    if _, err := c.Workspaces.Create(ctx, org, tfe.WorkspaceCreateOptions{Name: name}); err != nil {
        if !isConflict(err) { return err }
    }
    return nil
}

if isConflict(err) { /* workspace already exists; read it instead */ }

ws, err := b.client.Workspaces.Create(ctx, org, opts)
if err != nil {
    if isConflict(err) {
        ws, err = b.client.Workspaces.Read(ctx, org, name)
    }
    if err != nil {
        return nil, fmt.Errorf("error creating workspace %s: %v", name, err)
    }
}

When it happens

Trigger: terraform plan/apply with a cloud backend whose workspace name does not yet exist; Workspaces.Create returns an error (permission, 409 conflict, validation, 5xx, rate limit).

Common situations: Token lacks workspace-create permission; workspace name already exists but in a different project (conflict); invalid workspace name characters; org workspace limit reached; execution-mode or other create option rejected by API.

Related errors

• failed to create project %s: %v
• failed to retrieve project %s: %v
• failed to retrieve workspace %s: %v
• Failed to retrieve workspace %s: %v
• Attempted to find configured project %s but was unable to.

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