hashicorp/terraform · error

retrieving container client: %v

Error message

retrieving container client: %v

What it means

A wrapper error from Backend.Workspaces (backend_state.go:35-37). To list workspaces, the backend lazily builds the containers client via getContainersClient; if that construction fails (auth, key retrieval, or endpoint/URL problems), the error is surfaced here. It is an aggregate whose root cause is one of errors 142-145.

Source

Thrown at internal/backend/remote-state/azure/backend_state.go:37

)

const (
	// This will be used as directory name, the odd looking colon is simply to
	// reduce the chance of name conflicts with existing objects.
	keyEnvPrefix = "env:"
)

func (b *Backend) Workspaces() ([]string, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics
	prefix := b.keyName + keyEnvPrefix
	params := containers.ListBlobsInput{
		Prefix: &prefix,
	}

	ctx := newCtx()
	client, err := b.apiClient.getContainersClient(ctx)
	if err != nil {
		return nil, diags.Append(fmt.Errorf("retrieving container client: %v", err))
	}
	resp, err := client.ListBlobs(ctx, b.containerName, params)
	if err != nil {
		return nil, diags.Append(fmt.Errorf("listing blobs: %v", err))
	}

	envs := map[string]struct{}{}
	for _, obj := range resp.Blobs.Blobs {
		key := obj.Name
		if strings.HasPrefix(key, prefix) {
			name := strings.TrimPrefix(key, prefix)
			// we store the state in a key, not a directory
			if strings.Contains(name, "/") {
				continue
			}

			envs[name] = struct{}{}
		}

View on GitHub (pinned to c9def3e214)

Solutions

1. Read the message after 'retrieving container client:' to identify the root cause (auth, endpoint, or key)
2. Fix the underlying auth/endpoint issue (see the corresponding error 142-145 remediation)
3. Run 'terraform init -reconfigure' to rebuild the backend client from scratch
4. Verify the credential works against the data plane: az storage container list --account-name <account> --auth-mode login

Example fix

// before: SAS token without container-list permission causes client failure
terraform {
  backend "azurerm" {
    storage_account_name = "mystage"
    sas_token            = "sv=...&ss=f&srt=o"  // only file service, object scope
    ...
  }
}

// after: SAS granted service=b, resource types=co (service+container+object)
terraform {
  backend "azurerm" {
    storage_account_name = "mystage"
    sas_token            = "sv=...&ss=b&srt=sco&sp=rl"
    ...
  }
}

# Pre-flight: can we build the containers client (auth + endpoint)?
az storage container show --account-name "$ARM_STORAGE_ACCOUNT_NAME" -n "$ARM_CONTAINER_NAME" --auth-mode login >/dev/null 2>&1 \
  && echo "OK: container reachable" || echo "WARN: container/auth/endpoint issue -> error 148 possible; run 'terraform init -reconfigure' after fixing"

When it happens

Trigger: Produced at backend_state.go:35-37 during 'terraform workspace list/new/delete' when b.apiClient.getContainersClient(ctx) returns an error. The underlying cause is reported after the colon.

Common situations: Running 'terraform workspace list' with a misconfigured or expired credential; enabling lookup_blob_endpoint without resource_group_name; a SAS token that lacks container-list permission; a storage account the credential cannot reach.

Related errors

• retrieving key for Storage Account %q: %s
• listing blobs: %v
• listing Keys for %s: %+v
• new container client: %v
• One of `access_key`, `sas_token`, `use_azuread_auth` and `re

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