criticalIntermediateSymptom-first#s3#backend#bucket#state

S3 backend bucket missing — cannot initialize state backend

Error: Unable to find matching value for tag

Likely source:configurationdata-loss

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Error: Unable to find matching value for tag
  • S3 bucket does not exist: the bucket you are attempting to access must be addressed using the specified endpoint
  • terraform init fails with bucket not found

If the S3 bucket and its state file are both gone, the infrastructure is unmanaged. You may need to import resources from scratch.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Init error output

    terraform init 2>&1 | tail -20

  • Backend S3 bucket config

    grep -A10 'backend "s3"' *.tf

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • aws s3api head-bucket returns 404
  • terraform init fails with bucket not found

Confirm before fixing

aws s3api head-bucket --bucket <BUCKET> 2>&1
READ

Confirm the bucket does not exist

Fix

aws s3api create-bucket --bucket <BUCKET> --region <REGION>
CHANGE

Recreate the bucket (state data is lost unless there is a backup)

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
aws s3api head-bucket --bucket <BUCKET> 2>&1
READ

Check if the bucket exists

2
aws s3api create-bucket --bucket <BUCKET> --region <REGION>
CHANGE

Recreate the missing bucket

3
terraform init -migrate-state
CHANGE

Re-initialize the backend with the recreated bucket

Prevention

  • Enable S3 versioning and delete protection on the state bucket.
  • Enable S3 bucket replication or cross-region backup for state files.
  • Use AWS Organizations SCPs to prevent accidental bucket deletion.
  • Monitor S3 bucket deletion events with CloudTrail alerts.

Related runbooks

Same stack, same failure family — worth a skim.

Backend initialization required — run terraform initmedium

Backend initialization required: please run "terraform init"

TerraformFoundation2 causes
Open runbook
Corrupted local state — JSON parse error in state filecritical

Error: Error loading state: SyntaxError: JSON input

TerraformAdvanced2 causes
Open runbook
State file gone — everything shows as newcritical

terraform plan shows everything will be created (no existing resources in state)

TerraformProduction2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.