What causes "error getting bucket: %#v" in hashicorp/terraform?

Rename the bucket to a valid OSS name: lowercase letters, digits, hyphens only, 3-63 chars, no consecutive dots.

error getting bucket: %#v

Error message

error getting bucket: %#v

What it means

In Workspaces() (backend_state.go:59-61), b.ossClient.Bucket(b.bucketName) returned an error. The OSS SDK Bucket() is a local constructor that validates the bucket name; it fails before any network call when the name is malformed. This surfaces during workspace listing (terraform workspace list / StateMgr setup).

Source

Thrown at internal/backend/remote-state/oss/backend_state.go:61

	}
	if b.otsEndpoint != "" && b.otsTable != "" {
		_, err := b.otsClient.DescribeTable(&tablestore.DescribeTableRequest{
			TableName: b.otsTable,
		})
		if err != nil {
			return client, fmt.Errorf("error describing table store %s: %#v", b.otsTable, err)
		}
	}

	return client, nil
}

func (b *Backend) Workspaces() ([]string, tfdiags.Diagnostics) {
	var diags tfdiags.Diagnostics

	bucket, err := b.ossClient.Bucket(b.bucketName)
	if err != nil {
		return []string{""}, diags.Append(fmt.Errorf("error getting bucket: %#v", err))
	}

	var options []oss.Option
	options = append(options, oss.Prefix(b.statePrefix+"/"), oss.MaxKeys(1000))
	resp, err := bucket.ListObjects(options...)
	if err != nil {
		return nil, diags.Append(err)
	}

	result := []string{backend.DefaultStateName}
	prefix := b.statePrefix
	lastObj := ""
	for {
		for _, obj := range resp.Objects {
			// we have 3 parts, the state prefix, the workspace name, and the state file: <prefix>/<worksapce-name>/<key>
			if path.Join(b.statePrefix, b.stateKey) == obj.Key {
				// filter the default workspace
				continue

View on GitHub (pinned to c9def3e214)

Solutions

Rename the bucket to a valid OSS name: lowercase letters, digits, hyphens only, 3-63 chars, no consecutive dots.
Check the variable/locals feeding the bucket attribute for interpolation mistakes (trailing slash, empty string).
Confirm the bucket value is not being read from a stale .tfvars or environment override.

Example fix

// before
backend "oss" {
  bucket = "Terraform_State"  // invalid
}

// after
backend "oss" {
  bucket = "terraform-state"  // valid
}

Defensive patterns

Strategy: validation

Validate before calling

// Validate OSS bucket name locally before init.
var ossBucketRe = regexp.MustCompile(`^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$`)

func validBucketName(name string) bool {
    if !ossBucketRe.MatchString(name) || strings.Contains(name, "--") {
        return false
    }
    return len(name) >= 3 && len(name) <= 63
}

Try / catch

// Pure validation error; not retryable. Fix the name and re-init.
if !validBucketName(bucket) {
    return fmt.Errorf("invalid OSS bucket name %q", bucket)
}

Prevention

Normalize bucket names to lowercase-digits-hyphens at the source.
Add a CI lint that regex-checks the backend bucket attribute.
Avoid dynamic interpolation that can produce empty/uppercase values.

When it happens

Trigger: ossClient.Bucket(b.bucketName) returns a non-nil error because bucketName violates OSS naming rules (uppercase letters, underscores, wrong length, invalid characters). Bucket() is a pure validation, so this is not a network/permissions problem.

Common situations: Bucket name contains uppercase (e.g. TfState), underscores, is shorter than 3 or longer than 63 chars, starts/ends with a dash, or includes forbidden characters; bucket variable interpolated incorrectly producing an empty/garbage value.

Related errors

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