TerraformPilot

DevOps

Fix Terraform Error - Error Creating RDS - DBSubnetGroupNotFoundFault

Fix DBSubnetGroupNotFoundFault when creating RDS instances in Terraform. Create DB subnet groups with multi-AZ subnets, fix dependencies, and import...

LLuca Berton1 min read

Quick Answer

#

The DB subnet group doesn't exist or hasn't been created yet. RDS in a VPC requires a aws_db_subnet_group with subnets in at least two different AZs. Create the subnet group resource and reference it in your RDS instance.

The Error

# 
Error creating DB Instance: DBSubnetGroupNotFoundFault: 
DBSubnetGroup 'my-db-subnet-group' not found

What Causes This

#

1. Missing DB Subnet Group Resource

#

You referenced a db_subnet_group_name that doesn't exist in your config or wasn't created yet.

2. Name Mismatch

#

The name in aws_db_subnet_group doesn't match what's referenced in aws_db_instance.

3. Dependency Not Established

#

Terraform tried to create the RDS instance before the subnet group was ready.

4. Subnet Group Deleted Outside Terraform

#

Someone deleted it manually in the AWS Console.

How to Fix It

#

Solution 1: Create the DB Subnet Group

# 
data "aws_availability_zones" "available" {
  state = "available"
}
 
resource "aws_subnet" "private" {
  count             = 2
  vpc_id            = aws_vpc.main.id
  cidr_block        = cidrsubnet(aws_vpc.main.cidr_block, 8, count.index + 10)
  availability_zone = data.aws_availability_zones.available.names[count.index]
 
  tags = { Name = "private-${count.index}" }
}
 
resource "aws_db_subnet_group" "main" {
  name       = "${var.project}-db-subnet-group"
  subnet_ids = aws_subnet.private[*].id
 
  tags = { Name = "${var.project} DB subnet group" }
}
 
resource "aws_db_instance" "main" {
  identifier           = "${var.project}-db"
  engine               = "postgres"
  engine_version       = "16.1"
  instance_class       = "db.t3.micro"
  allocated_storage    = 20
  db_subnet_group_name = aws_db_subnet_group.main.name  # Reference the resource
  vpc_security_group_ids = [aws_security_group.db.id]
  skip_final_snapshot  = true
}

Solution 2: Import Existing Subnet Group

# 
# If the subnet group exists in AWS but not in Terraform state
terraform import aws_db_subnet_group.main my-db-subnet-group

Solution 3: Fix Name Mismatch

# 
# Check what exists in AWS
aws rds describe-db-subnet-groups \
  --query 'DBSubnetGroups[*].DBSubnetGroupName' \
  --output text
 
# Make sure the name matches your Terraform config

Common Mistakes

#
MistakeFix
Subnets in same AZUse subnets in 2+ different AZs
Hardcoded subnet group nameReference the Terraform resource name
No private subnetsCreate dedicated private subnets for RDS
String name vs resource referenceUse aws_db_subnet_group.main.name not a string

Troubleshooting Checklist

#
  1. ✅ Does aws_db_subnet_group exist in your config?
  2. ✅ Are subnets in at least 2 different AZs?
  3. ✅ Does the name in db_subnet_group_name match?
  4. ✅ Is the subnet group being created before the RDS instance?
#

Conclusion

#

DBSubnetGroupNotFoundFault means the subnet group doesn't exist when RDS tries to use it. Create an aws_db_subnet_group with subnets in at least two AZs, reference it by resource name (not hardcoded string), and let Terraform handle the dependency ordering.

#Terraform#Troubleshooting#DevOps#Error Fix#Infrastructure as Code

Share this article

Related articles