hashicorp/terraform · error

error deleting workspace %s: %v

Error message

error deleting workspace %s: %v

What it means

Emitted by remoteClient.Delete (backend_state.go:163-171) when Workspaces.Delete fails and the error is not tfe.ErrResourceNotFound. Delete is invoked to remove the workspace; ErrResourceNotFound is tolerated (already gone) but any other API failure is reported with the workspace name and cause.

Source

Thrown at internal/backend/remote/backend_state.go:167

	if errors.Is(err, tfe.ErrStateVersionUploadNotSupported) {
		// Create the new state with content included in the request (Terraform Enterprise v202306-1 and below)
		log.Println("[INFO] Detected that state version upload is not supported. Retrying using compatibility state upload.")
		return diags.Append(r.uploadStateFallback(ctx, stateFile, state, o))
	}
	if err != nil {
		r.stateUploadErr = true
		return diags.Append(fmt.Errorf("error uploading state: %v", err))
	}

	return nil
}

// Delete the remote state.
func (r *remoteClient) Delete() tfdiags.Diagnostics {
	var diags tfdiags.Diagnostics
	err := r.client.Workspaces.Delete(context.Background(), r.organization, r.workspace.Name)
	if err != nil && err != tfe.ErrResourceNotFound {
		return diags.Append(fmt.Errorf("error deleting workspace %s: %v", r.workspace.Name, err))
	}

	return nil
}

// EnableForcePush to allow the remote client to overwrite state
// by implementing remote.ClientForcePusher
func (r *remoteClient) EnableForcePush() {
	r.forcePush = true
}

// Lock the remote state.
func (r *remoteClient) Lock(info *statemgr.LockInfo) (string, error) {
	ctx := context.Background()

	lockErr := &statemgr.LockError{Info: r.lockInfo}

	// Lock the workspace.

View on GitHub (pinned to c9def3e214)

Solutions

1. Confirm and resolve preconditions in TFC UI: delete/queue resources, cancel pending runs, unlock the workspace first.
2. Grant the token's team/user the 'Admin' or 'Delete' permission on the workspace.
3. Retry after clearing the preconditions; transient 5xx resolve on retry.
4. If the workspace is already gone but a non-404 error returned, re-fetch the workspace to confirm its state before retrying.

Example fix

// before
Error: error deleting workspace dev: 422 workspace has locked state

// after: unlock then delete
$ terraform force-unlock <lock-id>  # or unlock in UI
$ terraform workspace delete dev

// Preflight: confirm the workspace has no locked state or pending runs before deleting.
ws, err := r.client.Workspaces.Read(ctx, r.organization, r.workspace.Name)
if err != nil { return err }
if ws.Locked { return errors.New("workspace is locked; unlock before deleting") }

// Tolerate already-deleted; surface everything else.
if err := r.client.Workspaces.Delete(ctx, r.organization, r.workspace.Name); err != nil && err != tfe.ErrResourceNotFound {
    return fmt.Errorf("error deleting workspace %s: %v", r.workspace.Name, err)
}

When it happens

Trigger: Calling workspace deletion while the workspace has locked state, pending runs, resources, or the token lacks admin/delete permission; or the TFC API returns 5xx/network error.

Common situations: Attempting to delete a workspace that still manages resources or has an in-flight run; insufficient permissions on the service account; TFC transient outage; workspace is locked by another user.

Related errors

• Expected a single argument: NAME.
• error deleting workspace %s: %w
• failed to empty bucket %v: %v
• Error creating workspace %s: %v
• workspace %s not found For security, %s returns '404 Not Fo

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