DoonopsEdTech
Language

Troubleshooting · Lesson 28 of 30

Troubleshooting Common Errors

Source: doonops-curriculum/troubleshooting--common-errors.md

Doonops lesson

Goal

Fix the errors you will actually see in labs — credentials, permissions, state lock, wrong region, and failed apply.

Simple explanation

When Terraform fails, read the red error from bottom to top. Most beginner issues are: wrong AWS keys, wrong region, missing IAM permission, or state locked by another terminal.

Technical view

Use TF_LOG=DEBUG sparingly. terraform validate / fmt before plan. State lock via DynamoDB. Provider region must match resource region. IAM policy must allow service API calls.

Steps

  1. Read error message
  2. Match to table below
  3. Fix one thing
  4. terraform plan again

Deep explanation

Layman words first, then technical detail — read slowly

Error cheat sheet (layman + fix)

Error / symptomLikely causeWhat to do
No valid credential sourcesAWS CLI not configuredRun aws configure → test aws sts get-caller-identity
AccessDenied / not authorizedIAM user missing permissionAdd policy (lab: PowerUserAccess) or ask admin
Error acquiring the state lockAnother apply running or crashedWait; close other terminal; only then terraform force-unlock ID
InvalidAMIID.NotFoundAMI ID wrong for regionUse data source aws_ami or pick AMI in same region as provider
BucketAlreadyExistsS3 bucket name global uniqueChange bucket name suffix in variables
Unsupported attributeProvider version / wrong output nameRun terraform init -upgrade, check module docs
Unexpected billForgot destroyterraform destroy in lab folder; check AWS Billing dashboard

Safe debug order

  1. terraform fmt -check
  2. terraform validate
  3. terraform plan (read carefully)
  4. Only then apply
# Extra logs (short time only)
export TF_LOG=ERROR
terraform plan

Project files for this lab

Full implementation folder — copy all files, then run terraform commands

Lab project files (full folder)

Copy every file below into one folder — same as a real repo module. Then run the local lab steps.

Suggested folder: Suggested path: ~/doonops-terraform/24-troubleshooting/

README.mdSee file purpose in the code below
# Troubleshooting practice

1. Run plan without aws configure — read error
2. Fix configure
3. See state lock with two terminals (optional)

Practice fixing (optional)

Prerequisites

  • Completed at least one AWS lab
  1. Intentionally run terraform plan without aws configure — read credential error.
  2. Fix with aws configure — plan should work.
  3. Run plan in two terminals at once on same state — see lock message (then stop one).

Remember

  • Know where credentials live (aws configure, not in Git)
  • plan before apply
  • destroy after labs

Module check — did you get it?

2–3 quick questions before the next module

Troubleshooting — quick check

Quick check — did this module stick?

1. Error "Error acquiring the state lock" — first step?

  • Delete S3 bucket
  • Wait / identify who is running apply / force-unlock only if sure
  • Reinstall Windows
  • Change region