How do I troubleshoot Amazon EC2 RunInstances API calls that fail with the "InvalidBlockDeviceMapping" error?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

If block devices are incorrectly configured, then Amazon EC2 RunInstances API calls fail with the "InvalidBlockDeviceMapping" error. To resolve the issue, use the following steps based on the error message that you receive.

Encryption errors

If you launch instances from encrypted Amazon Machine Images (AMIs), then you receive an error message similar to the following:

"An error occurred (InvalidBlockDeviceMapping) when calling the RunInstances operation: Cannot create unencrypted volume from encrypted snapshot snap-1234567890abcdef0"

Amazon EC2 can't create unencrypted volumes from encrypted snapshots. When you launch instances from encrypted AMIs, you must explicitly set the encrypted flag to True in your block device parameter.

To resolve this error, set the encrypted flag to True in your RunInstances API call, use the block device mappings parameter.

aws ec2 run-instances --image-id IMAGE-ID --instance-type t3.micro \
--key-name KEY-PAIR \
--block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"Encrypted":true,"DeleteOnTermination":true,"Iops":3000,"KmsKeyId":"arn:aws:KMS-KEY/1234abcd-12ab-34cd-56ef-1234567890ab","VolumeSize":8,"VolumeType":"gp3","Throughput":125}}' \
--network-interfaces '{"AssociatePublicIpAddress":true,"DeviceIndex":0,"Groups":["sg-SECURITY-GROUP-ID"]}'

Note: Replace IMAGE-ID with your AMI ID and KEY-PAIR with your key pair name. Replace KMS-KEY with your AWS Key Management Service (AWS KMS) key ARN and SECURITY-GROUP-ID with your security group ID.

Cross-account AMI sharing errors

You can't share AMIs backed by snapshots encrypted with AWS managed keys across accounts. If you back AMIs by snapshots encrypted with AWS managed keys, then you receive an error message similar to the following:

"An error occurred (InvalidBlockDeviceMapping) when calling the RunInstances operation: The KMS key used to encrypt the volume is not accessible across accounts. Please verify KMS key permissions"

To resolve this error, create a customer managed AWS KMS key for the AMI snapshots. Copy the AMI with a customer managed key, and then share both the AMI and AWS KMS key permissions with the destination account.

Note: Confirm that the AWS Identity and Access Management (IAM) role has permissions to access the AWS KMS key of the encrypted snapshot. For cross-account access, see Allowing users in other accounts to use a KMS key.

To create a customer managed AWS KMS key and share AMIs across accounts, complete the following steps:

1. To create a customer managed KMS key in the source account, run the following create-key AWS CLI command:

   aws kms create-key --description "Cross-account AMI sharing key" --key-usage ENCRYPT_DECRYPT

   Note: Save the key ID from the output for use in subsequent steps.
2. To create a key policy that allows cross-account access, run the following put-key-policy AWS CLI command:

   `aws kms put-key-policy --key-id KEY-ID --policy-name default --policy '{   "Version": "2012-10-17",   "Statement": [     {       "Sid": "Enable IAM User Permissions",       "Effect": "Allow",       "Principal": {"AWS": "arn:aws:iam::SOURCE-ACCOUNT-ID:root"},       "Action": "kms:*",       "Resource": "*"`
       },`     {       "Sid": "Allow cross-account access",       "Effect": "Allow",       "Principal": {"AWS": "arn:aws:iam::DESTINATION-ACCOUNT-ID:root"},       "Action": [         "kms:Encrypt",         "kms:Decrypt",         "kms:ReEncrypt*",         "kms:GenerateDataKey*",         "kms:DescribeKey"       ],       "Resource": "*"     }   ] }'`

   Note: Replace KEY-ID with the customer managed KMS key ID from step 1, SOURCE-ACCOUNT-ID with your source account ID, and DESTINATION-ACCOUNT-ID with the destination account ID.
3. To copy the AMI with the customer managed key, run the following copy-image AWS CLI command:

   aws ec2 copy-image --source-image-id SOURCE-IMAGE-ID --source-region REGION --name "Cross-account-AMI" --kms-key-id KEY-ID `1234abcd-12ab-34cd-56ef-1234567890ab`

   Note: Replace SOURCE-IMAGE-ID with your source AMI ID, REGION with your AWS Region, and KEY-ID with the customer managed KMS key ID from step 1.
4. To share the AMI with the destination account, run the following modify-image-attribute AWS CLI command:

   aws ec2 modify-image-attribute --image-id `SOURCE-IMAGE-ID` --launch-permission "Add=[{UserId=DESTINATION-ACCOUNT-ID}]"

   Note: Replace SOURCE-IMAGE-ID with the copied source AMI ID from step 3 and DESTINATION-ACCOUNT-ID with the destination account ID.
5. In the destination account, create an IAM policy that allows access to the shared KMS key:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "kms:Encrypt",
           "kms:Decrypt",
           "kms:ReEncrypt*",
           "kms:GenerateDataKey*",
           "kms:DescribeKey"
         ],
         "Resource": "arn:aws:kms:REGION:SOURCE-ACCOUNT-ID:key/KEY-ID"
       }
     ]
   }

   Note: Replace REGION with your AWS Region, SOURCE-ACCOUNT-ID with your source account ID, and KEY-ID with the customer managed KMS key ID from step 1.

For more information, see How to share encrypted AMIs across accounts to launch encrypted EC2 instances.

Volume size errors

The volume size in your RunInstances API call must match or exceed the original snapshot size. If the specified volume size is smaller than the snapshot size, then you receive an error message similar to the following:

"An error occurred (InvalidBlockDeviceMapping) when calling the RunInstances operation: Volume size '8' is smaller than snapshot 'snap-1234567890abcdef0' size '10' for /dev/xvda"

Note: Amazon Elastic Block Store (Amazon EBS) doesn't allow volume size reduction. For more information on storage capacity limits, see Amazon EBS volume constraints.

To resolve this error, check the original volume size before you create the snapshot. Then, specify a volume size that matches or exceeds the original volume size.

Complete the following steps:

1. To check the original volume size, run the following describe-volumes AWS CLI command:

   aws ec2 describe-volumes --volume-ids `VOLUME-ID` --query "Volumes.Size"

   Note: Replace VOLUME-ID with your volume ID.
2. To verify the snapshot's volume size, run the following describe-snapshots AWS CLI command:

   aws ec2 describe-snapshots --snapshot-ids `SNAPSHOT-ID` --query "Snapshots.VolumeSize"

   Note: Replace SNAPSHOT-ID with your snapshot ID.
3. To create volumes from the snapshot with the correct size, run the following run-instances AWS CLI command:

   aws ec2 run-instances --image-id `AMI-ID` --instance-type t3.micro --block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":VOLUME-SIZE,"VolumeType":"gp3"}}'

   Note: Replace AMI-ID with your AMI ID and VOLUME-SIZE with a size that matches or exceeds the original volume size from step 1.

Snapshot ID errors

Amazon EC2 requires root volumes to use the snapshot IDs associated with the AMI. You can't modify root volume snapshot IDs from the AMI defaults. If you modify root volume snapshot IDs from AMI defaults, then you receive an error message similar to the following:

"An error occurred (InvalidBlockDeviceMapping) when calling the RunInstances operation: Invalid snapshot ID snap-1234567890abcdef0 specified for root device /dev/xvda. Expected snapshot-id: snap-0987654321fedcba0"

To resolve snapshot ID errors, find the correct snapshot IDs associated with your AMI, and then use the IDs in your RunInstances API call.

Complete the following steps:

1. To find the correct snapshot IDs associated with your AMI, run the following describe-images AWS CLI command:

   aws ec2 describe-images --image-ids `AMI-ID` --query "Images[*].BlockDeviceMappings[*].Ebs.SnapshotId"

   Note: Replace AMI-ID with your AMI ID.
2. To use the snapshot IDs from the output in your RunInstances API call, run the following run-instances AWS CLI command:

   aws ec2 run-instances --image-id AMI-ID --instance-type t3.micro --block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"Encrypted":true,"DeleteOnTermination":true,"SnapshotId":"SNAPSHOT-ID","VolumeSize":8,"VolumeType":"gp3"}}'

   Note: Replace AMI-ID with your AMI ID and SNAPSHOT-ID with the actual snapshot ID returned from step 1. For root volumes, you must use the exact snapshot ID associated with the AMI.

Throughput parameter errors

Throughput parameters only apply to gp3 volume types. Amazon EBS gp2 volumes deliver throughput between 128 MiBps and 250 MiBps automatically and don't accept custom throughput values. If you try to specify throughput values for gp2 volumes, then you receive an error message similar to the following:

"An error occurred (InvalidBlockDeviceMapping) when calling the RunInstances operation: Parameter throughput is not supported for gp2 volumes. Consider using gp3 volume type instead"

To resolve this error, remove the throughput parameter from RunInstances API calls when you use gp2 volume types. Alternatively, change the volume type to gp3 to specify throughput values.

Complete the following steps:

1. To use gp2 volume type without throughput parameters, run the following run-instances AWS CLI command:

   aws ec2 run-instances --image-id AMI-ID --instance-type t3.micro --block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":VOLUME-SIZE,"VolumeType":"gp2"}}'

   Note: Replace AMI-ID with your AMI ID and VOLUME-SIZE with your desired volume size.
2. To use gp3 volume type with throughput parameters, run the following run-instances AWS CLI command:

   aws ec2 run-instances --image-id AMI-ID --instance-type t3.micro --block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":VOLUME-SIZE,"VolumeType":"gp3","Throughput":THROUGHPUT-VALUE}}'

   Note: Replace AMI-ID with your AMI ID, VOLUME-SIZE with your desired volume size, and THROUGHPUT-VALUE with your desired throughput value (125-1000 MiBps).

For more information, see gp2 volume performance.

Launch template device name errors

If you recreate a launch template before 2024, then your template might contain invalid NVME device names for instance store volumes. If your launch templates contain invalid NVME device names, then you receive an error message similar to the following:

"An error occurred (InvalidBlockDeviceMapping) when calling the RunInstances operation: Invalid device mapping for instance store volumes. Please verify device naming convention"

To resolve this error, create a new launch template version with updated device configurations.

Complete the following steps:

1. To retrieve the launch template version data for editing, run the following describe-launch-template-versions AWS CLI command:

   aws ec2 describe-launch-template-versions --launch-template-name TEMPLATE-NAME --versions '["VERSION-NUMBER"]' --query "LaunchTemplateVersions.LaunchTemplateData" > template-data.txt

   Note: Replace TEMPLATE-NAME with your launch template name and VERSION-NUMBER with the version you want to edit.
2. To create a new launch template version with updated configurations, run the following create-launch-template-version AWS CLI command:

   aws ec2 create-launch-template-version --launch-template-name TEMPLATE-NAME --launch-template-data "$(cat template-data.txt)"

   Note: Replace TEMPLATE-NAME with your launch template name. Before you run this command, make sure that you update the device configurations in the template-data.txt file.