hashicorp/terraform · error

Failed to get existing workspaces

Error message

Failed to get existing workspaces: %s

What it means

Returned from `Meta.selectWorkspace` when `b.Workspaces()` returns diagnostics that have errors AND the error string is not the `backend.ErrWorkspacesNotSupported` sentinel. The backend was asked to enumerate workspaces and failed for a reason other than not supporting the concept at all.

Solutions

  1. Inspect the wrapped `%s` (the diagnostics error) for the HTTP status or filesystem error.
  2. For cloud backends, verify the token has at least `read-workspaces` permission on the organization.
  3. Confirm the `organization` and `hostname` in the `cloud` block are correct.
  4. Run `terraform init` to re-establish connectivity and re-authenticate if needed.
  5. For local backends, check permissions on the state directory.

Example fix

// before: token lacks read permission
cloud { organization = "acme" workspaces { name = "prod" } }
# grant 'Read Workspaces' to the token's team in HCP Terraform org settings,
# then
terraform init
terraform plan
Defensive patterns

Strategy: try-catch

Validate before calling

// For cloud backends, pre-check token permissions / org access.
// Ensure the token can list workspaces before running selectWorkspace.
client, _ := tfe.NewClient(&tfe.Config{Token: tok, Address: addr})
if _, err := client.Organizations.Read(ctx, org); err != nil {
    return fmt.Errorf("token cannot access org %s: %w", org, err)
}

Type guard

// Skip the error if the backend simply lacks workspace support.
if diags.Err().Error() == backend.ErrWorkspacesNotSupported.Error() { return nil }

Try / catch

// Distinguish 'not supported' (benign) from real listing failures.
if diags.HasErrors() && diags.Err().Error() != backend.ErrWorkspacesNotSupported.Error() {
    return fmt.Errorf("Failed to get existing workspaces: %s", diags.Err())
}

Prevention

When it happens

Trigger: `b.Workspaces()` issues the backend's workspace-listing routine — for the cloud backend this is an API call filtered by `workspaces.tags`/`workspaces.name`; for the local backend it is a directory read. Failures include API 5xx/4xx, permission errors, network failures, or a local filesystem read error. The early `ErrWorkspacesNotSupported` short-circuit means this only fires for backends that DO support workspaces but failed to list them.

Common situations: HCP Terraform API token lacks permission to list workspaces in the organization; `workspaces.tags` filter references tags that cause a server error; network blip to `app.terraform.io`; local backend cannot read `.terraform/terraform.tfstate.d/` due to permissions; organization name typo in the `cloud` block.

Related errors

AI-assisted analysis of hashicorp/terraform@d32a084675 (2026-08-11). Data as JSON: /api/errors/3f3ae4087e79f4fc. Report an issue: GitHub.

Appendix: source

Thrown at internal/command/meta_backend.go:246

		m.backendConfigState = &workdir.BackendConfigState{
			Type:      "local",
			ConfigRaw: json.RawMessage("{}"),
		}
	}

	return local, diags
}

// selectWorkspace gets a list of existing workspaces and then checks
// if the currently selected workspace is valid. If not, it will ask
// the user to select a workspace from the list.
func (m *Meta) selectWorkspace(b backend.Backend) error {
	workspaces, diags := b.Workspaces()
	if diags.HasErrors() && diags.Err().Error() == backend.ErrWorkspacesNotSupported.Error() {
		return nil
	}
	if diags.HasErrors() {
		return fmt.Errorf("Failed to get existing workspaces: %s", diags.Err())
	}
	if diags.HasWarnings() {
		log.Printf("[WARN] selectWorkspace: warning(s) returned when getting workspaces: %s", diags.ErrWithWarnings())
	}
	if len(workspaces) == 0 {
		if c, ok := b.(*cloud.Cloud); ok && m.input {
			// len is always 1 if using Name; 0 means we're using Tags and there
			// aren't any matching workspaces. Which might be normal and fine, so
			// let's just ask:
			name, err := m.UIInput().Input(context.Background(), &terraform.InputOpts{
				Id:          "create-workspace",
				Query:       "\n[reset][bold][yellow]No workspaces found.[reset]",
				Description: fmt.Sprintf(inputCloudInitCreateWorkspace, c.WorkspaceMapping.DescribeTags()),
			})
			if err != nil {
				return fmt.Errorf("Couldn't create initial workspace: %w", err)
			}
			name = strings.TrimSpace(name)

View on GitHub (pinned to d32a084675)