hashicorp/terraform · error

new container client: %v

Error message

new container client: %v

What it means

In getContainersClient the backend derives a blob base URI (either from the looked-up account detail endpoint or from a naive guess) and then calls containers.NewWithBaseUri(baseUri). This error (api_client.go:221-223) means the resulting URI was empty or unparseable, so the Giovanni containers client could not be constructed. It is a configuration/endpoint-resolution failure rather than a network failure.

Source

Thrown at internal/backend/remote-state/azure/api_client.go:223

	var baseUri string
	if c.accountDetail != nil {
		// Use the actual blob endpoint if available
		pBaseUri, err := c.accountDetail.DataPlaneEndpoint(EndpointTypeBlob)
		if err != nil {
			return nil, err
		}
		baseUri = *pBaseUri
	} else {
		baseUri, err = naiveStorageAccountBlobBaseURL(c.environment, c.storageAccountName)
		if err != nil {
			return nil, err
		}
	}

	containersClient, err := containers.NewWithBaseUri(baseUri)
	if err != nil {
		return nil, fmt.Errorf("new container client: %v", err)
	}

	switch {
	case c.sasToken != "":
		log.Printf("[DEBUG] Building the Container Client from a SAS Token")
		c.configureClient(containersClient.Client, nil)
		containersClient.Client.AppendRequestMiddleware(func(r *http.Request) (*http.Request, error) {
			if r.URL.RawQuery == "" {
				r.URL.RawQuery = c.sasToken
			} else if !strings.Contains(r.URL.RawQuery, c.sasToken) {
				r.URL.RawQuery = fmt.Sprintf("%s&%s", r.URL.RawQuery, c.sasToken)
			}
			return r, nil
		})
		return containersClient, nil

	case c.accessKey != "":
		log.Printf("[DEBUG] Building the Container Client from an Access Key")

View on GitHub (pinned to c9def3e214)

Solutions

1. Enable endpoint lookup so the real blob endpoint is fetched: set lookup_blob_endpoint = true and resource_group_name
2. Verify the environment matches your cloud: use environment = "usgovernment" / "china" / "public", or set metadata_host
3. Confirm the storage account exposes a blob endpoint: az storage account show -n <account> --query primaryEndpoints.blob
4. For air-gapped clouds, ensure the metadata service exposes a storage domain suffix

Example fix

// before: naive endpoint guess fails on a sovereign cloud
terraform {
  backend "azurerm" {
    storage_account_name = "mystorage"
    container_name       = "tfstate"
    key                  = "prod.tfstate"
    environment          = "usgovernment"
  }
}

// after: look up the real blob endpoint via ARM
terraform {
  backend "azurerm" {
    storage_account_name  = "mystage"
    container_name        = "tfstate"
    key                   = "prod.tfstate"
    environment           = "usgovernment"
    lookup_blob_endpoint  = true
    resource_group_name   = "rg-tfstate"
    subscription_id       = "00000000-0000-0000-0000-000000000000"
  }
}

# Validate the blob endpoint resolves before terraform init
BLOB=$(az storage account show -n "$ARM_STORAGE_ACCOUNT_NAME" --query primaryEndpoints.blob -o tsv 2>/dev/null)
[ -n "$BLOB" ] && echo "OK blob endpoint: $BLOB" || echo "FAIL: no blob endpoint -> set lookup_blob_endpoint=true + resource_group_name"
# for sovereign clouds confirm the environment has a storage suffix
az cloud show --query suffixes.storageEndpoint -o tsv

When it happens

Trigger: Produced when containers.NewWithBaseUri(baseUri) returns an error because baseUri is empty or malformed. baseUri comes from either accountDetail.DataPlaneEndpoint(EndpointTypeBlob) (which can be nil/empty if the account has no blob endpoint) or naiveStorageAccountBlobBaseURL, which fails separately when the environment has no storage domain suffix.

Common situations: Using a sovereign/air-gapped cloud whose environment definition has no storage domain suffix; the storage account's PrimaryEndpoints.Blob is nil (account not fully provisioned, or non-StorageV2 with no blob endpoint); an invalid environment name or metadata_host that resolves to an environment lacking storage endpoints.

Related errors

• `resource_group_name` is required when `lookup_blob_endpoint
• determining %s endpoint for %s: missing primary endpoint
• no storage domain suffix defined for environment: %s
• populating details for %s: %+v
• retrieving key for Storage Account %q: %s

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