init fails: S3 bucket does not exist (backend not bootstrapped)
Fixes Terragrunt init failing because the S3 state bucket doesn't exist, by bootstrapping it. Use when init fails on a missing bucket and you expected Terragrunt to create it. Not for wrong bucket names or regions.
TL;DR: Terragrunt does NOT create your state bucket by default (--backend-bootstrap defaults to false), so init fails with "bucket not found" on a fresh environment. Run terragrunt backend bootstrap once to create it.
Initializing the backend...
Error: Failed to get existing workspaces: S3 bucket "my-state-bucket" does not exist.(Exact wording varies; the constant is init failing because the bucket named in remote_state isn't there.)
Steps
Check whether the bucket exists at all, and as whom:
aws s3api head-bucket --bucket [bucket]andaws sts get-caller-identity. Expected: you know if it's missing vs misnamed vs a credentials problem.If it's genuinely missing, create it through Terragrunt:
terragrunt backend bootstrap. Expected: bucket created and reconciled with yourremote_stateconfig (versioning etc.).Or enable it per-run:
terragrunt run --backend-bootstrap -- init. Expected: init creates what's missing, then proceeds.Re-run init. Expected: backend initializes.
When this applies
- First deploy to a new environment/account; the bucket was never created.
- You assumed Terragrunt creates backend resources automatically.
When it doesn't apply
- The bucket exists but access is denied: that's IAM, not bootstrapping.
disable_init = truein theremote_stateblock: then nothing is created regardless of the flag; fix the block.- Azure (
azurerm) backend: Terragrunt does NOT bootstrap Azure storage at all; create the account and container out of band.
Tool versions
All Terragrunt 1.x. Only s3 and gcs backends support automatic creation.
Why it happens
Backend bootstrapping is opt-in because creating cloud resources as a side effect of init surprises people. The default keeps init read-only with respect to the account, which means fresh environments need one explicit bootstrap.
Edge cases
- For S3, bootstrap also UPDATES an existing bucket to match
remote_state(e.g. versioning), so it's worth running against buckets that already exist. - A bucket name that's wrong (typo) fails the same way;
head-bucketdistinguishes "missing" from "misnamed" before you bootstrap the wrong name.