mediumFoundationSymptom-first#backend#init#s3#remote-state

Backend initialization required — run terraform init

Backend initialization required: please run "terraform init"

Likely source:configuration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Backend initialization required: please run "terraform init"
  • terraform plan fails with backend configuration changed
  • After cloning a repo, first terraform command fails

terraform init is required whenever the backend block changes or after a fresh clone. Always run it before plan/apply.

Evidence to grab

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

  • Error message

    terraform plan 2>&1 | head -10

  • Current backend config

    grep -A10 'backend' *.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

  • New backend block added to root module
  • Bucket/key/region changed in existing backend block

Confirm before fixing

terraform init 2>&1 | tail -5
READ

Run init and check the migration prompt

Fix

terraform init -migrate-state
CHANGE

Migrate state to the new backend

Expected: Successfully configured the backend "s3"

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
terraform init -migrate-state
CHANGE

Initialize the backend, migrating state if necessary

2
terraform plan
READ

Verify the plan runs without init errors

Prevention

  • Run terraform init in CI before plan/apply steps.
  • Use -backend-config for environment-specific backend settings.
  • Document the init step in the repo README for new contributors.
  • Use terraform cloud or Atlantis for automated init management.

Related runbooks

Same stack, same failure family — worth a skim.

S3 backend bucket missing — cannot initialize state backendcritical

Error: Unable to find matching value for tag

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

Error: Error loading state: SyntaxError: JSON input

TerraformAdvanced2 causes
Open runbook

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