hashicorp/terraform · error

acl value invalid, expected

Error message

acl value invalid, expected %s or %s, got %s

What it means

Schema-level ValidateFunc for the COS backend 'acl' attribute applied to the state object. Only 'private' and 'public-read' are accepted; any other value is rejected at terraform init time. State files should normally be 'private'.

Solutions

1. Set acl = 'private' (the default and recommended for state) or acl = 'public-read'.
2. Re-run terraform init.

Example fix

// before
terraform {
  backend "cos" {
    acl = "public-read-write"
  }
}

// after
terraform {
  backend "cos" {
    acl = "private"
  }
}

// Validate the COS backend acl value before terraform init.
func validateCOSACL(acl string) error {
    if acl != "private" && acl != "public-read" {
        return fmt.Errorf("acl value invalid, expected %s or %s, got %s", "private", "public-read", acl)
    }
    return nil
}

When it happens

Trigger: terraform init with acl set to anything other than 'private' or 'public-read' (e.g. 'public-read-write', 'bucket-owner-full-control', etc.).

Common situations: User copies an S3 ACL value not supported by COS; tries to use a bucket-level canned ACL; sets 'public-read-write' intending wide access.

Related errors

• Invalid URL: must be
• key can not start and end with '/'
• prefix must not start with '/' or './'
• cannot be higher than
• cannot be lower than

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

Appendix: source

Thrown at internal/backend/remote-state/cos/backend.go:167

					}
					return nil, nil
				},
			},
			"encrypt": {
				Type:        schema.TypeBool,
				Optional:    true,
				Description: "Whether to enable server side encryption of the state file",
				Default:     true,
			},
			"acl": {
				Type:        schema.TypeString,
				Optional:    true,
				Description: "Object ACL to be applied to the state file",
				Default:     "private",
				ValidateFunc: func(v interface{}, s string) ([]string, []error) {
					value := v.(string)
					if value != "private" && value != "public-read" {
						return nil, []error{fmt.Errorf(
							"acl value invalid, expected %s or %s, got %s",
							"private", "public-read", value)}
					}
					return nil, nil
				},
			},
			"accelerate": {
				Type:        schema.TypeBool,
				Optional:    true,
				Description: "Whether to enable global Acceleration",
				Default:     false,
			},
			"assume_role": {
				Type:        schema.TypeSet,
				Optional:    true,
				MaxItems:    1,
				Description: "The `assume_role` block. If provided, terraform will attempt to assume this role using the supplied credentials.",
				Elem: &schema.Resource{

View on GitHub (pinned to d32a084675)