How does the backend_config actually work?

[TurboNHS]

I have:

backend_config: bucket="my-prefix-${{ env.ENVIRONMENT }}-state"

and the backend config in the directory:

terraform {
  backend "s3" {
    encrypt      = true
    use_lockfile = true
    key          = "state/mydir.tfstate"
  }
  required_version = "= 1.13.2"
}

I don't use workspaces, so the default is fine by me.

This is all computed correctly. However, the job fails with:

2026-05-14T16:18:48.9386916Z �Error: �Failed to get existing workspaces: Unable to list objects in S3 bucket "\"my-prefix-myenv-state\"" with prefix "env:/": operation error S3: ListObjectsV2, https response error StatusCode: 400, RequestID: <REQUEST_ID_STRING>, HostID: <HOST_ID_STRING>, api error InvalidBucketName: The specified bucket is not valid.

Where does the prefix env:/ come from?!

[dflook]

Hi @TurboNHS, I think you are running into a quirk with Terraform's -backend-config flag that backend_config uses. Unlike in a backend config file, you have to specify key=value without any quotes.

i.e.

backend_config: bucket=my-prefix-${{ env.ENVIRONMENT }}-state

Can you give that a try? env:/ is a default prefix when working with workspaces - I think terraform is just confused here and giving an unhelpful error.

[TurboNHS]

Awesome, thanx! That worked perfectly..

Although, in the script that I'm transition away from (hoping for less code to maintain :), I have:

terraform init -upgrade -reconfigure -backend-config="bucket=${TF_BUCKET}"

Which works fine.