highIntermediateSymptom-first#ebs#attach#volume#az

EBS volume stuck in attaching state

aws ec2 describe-volumes shows State: attaching for minutes

Likely source:availabilityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • aws ec2 describe-volumes shows State: attaching for minutes
  • Block device missing inside the instance (lsblk does not show it)
  • A pod/VM mount that depends on the volume never comes ready

Evidence to grab

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

  • Volume state

    aws ec2 describe-volumes --volume-ids <VOLUME-ID> --query 'Volumes[0].{State:State,AvailabilityZone:AvailabilityZone,Attachments:Attachments}'

  • Instance AZ and device mapping

    aws ec2 describe-instances --instance-ids <INSTANCE-ID> --query 'Reservations[0].Instances[0].{AZ:Placement.AvailabilityZone,Devices:BlockDeviceMappings}'

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

  • Volume AZ differs from instance AZ
  • Attach simply never completes

Confirm before fixing

aws ec2 describe-volumes --volume-ids <VOLUME-ID> --query 'Volumes[0].AvailabilityZone' && aws ec2 describe-instances --instance-ids <INSTANCE-ID> --query 'Reservations[0].Instances[0].Placement.AvailabilityZone'
READ

Compare the two AZs

Fix

aws ec2 create-snapshot --volume-id <VOLUME-ID> --description 'error-az-recovery' && aws ec2 create-volume --snapshot-id <SNAPSHOT-ID> --availability-zone <INSTANCE-AZ>
CHANGE

Create a volume in the correct AZ (or move the instance)

Expected: snapshot- and vol- IDs

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 ec2 describe-volumes --volume-ids <VOLUME-ID> --query 'Volumes[0].{State:State,AvailabilityZone:AvailabilityZone,Attachments:Attachments}'
READ

Read state, AZ, and current attachments

2
aws ec2 describe-instances --instance-ids <INSTANCE-ID> --query 'Reservations[0].Instances[0].Placement.AvailabilityZone'
READ

Confirm the instance AZ

3
aws ec2 detach-volume --volume-id <VOLUME-ID> --instance-id <INSTANCE-ID> --force
CHANGE

Force a clean detach when the state is wedged (force available from CLI)

4
aws ec2 attach-volume --volume-id <VOLUME-ID> --instance-id <INSTANCE-ID> --device <DEVICE-NAME>
CHANGE

Re-attach and verify with lsblk from the host

Prevention

  • Enforce volume/instance AZ pairing in IaC (data_aws_availability_zone checks).
  • Alert on volume state not equal to in-use for more than 5 minutes.
  • Never script attach without first reading the volume's current attachment list.

Related runbooks

Same stack, same failure family — worth a skim.

Encrypted EBS volume fails to attach — KMS permission problemhigh

AttachVolume fails or volume stays in 'attaching' for encrypted volumes

AWSAdvanced3 causes
Open runbook
EBS snapshot stuck in 'creating' statemedium

aws ec2 describe-snapshots shows State: pending for hours

AWSAdvancedUSE3 causes
Open runbook
Root EBS volume filling up — instance degradedcritical

df -h / shows 95-100% usage on the root device

AWSIntermediateUSE3 causes
Open runbook

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