TerraformPilot

DevOps

Fix Terraform Error - Error Creating Neptune Cluster - DBClusterNotFoundFault

Fix DBClusterNotFoundFault when creating AWS Neptune clusters in Terraform. Handle subnet group configuration, parameter groups, and IAM role dependencies.

LLuca Berton1 min read

Quick Answer

#

The Neptune cluster creation failed because of missing or misconfigured dependencies — typically the DB subnet group doesn't exist, the VPC subnets span fewer than 2 AZs, or the IAM role isn't ready. Fix subnet group coverage, ensure 2+ AZs, and add explicit depends_on for IAM roles.

The Error

# 
Error: error creating Neptune Cluster: DBClusterNotFoundFault: 
DB cluster not found
Error: error creating Neptune Cluster: 
DBSubnetGroupDoesNotCoverEnoughAZs

What Causes This

#
  • Subnet group covers only 1 AZ — Neptune requires at least 2 Availability Zones
  • Subnet group doesn't exist — referenced by name but not created yet
  • IAM role not ready — eventual consistency delay on the role
  • Parameter group missing — custom parameter group hasn't been created

How to Fix It

#

Solution 1: Complete Neptune Configuration

# 
resource "aws_neptune_subnet_group" "main" {
  name       = "${var.project}-neptune"
  subnet_ids = aws_subnet.private[*].id  # Must span 2+ AZs
 
  tags = { Name = "${var.project}-neptune-subnet-group" }
}
 
resource "aws_neptune_cluster_parameter_group" "main" {
  family = "neptune1.3"
  name   = "${var.project}-neptune-params"
 
  parameter {
    name  = "neptune_enable_audit_log"
    value = "1"
  }
}
 
resource "aws_neptune_cluster" "main" {
  cluster_identifier                  = "${var.project}-neptune"
  engine                              = "neptune"
  neptune_subnet_group_name           = aws_neptune_subnet_group.main.name
  neptune_cluster_parameter_group_name = aws_neptune_cluster_parameter_group.main.name
  vpc_security_group_ids              = [aws_security_group.neptune.id]
  iam_database_authentication_enabled = true
  skip_final_snapshot                 = true
 
  depends_on = [aws_neptune_subnet_group.main]
}
 
resource "aws_neptune_cluster_instance" "main" {
  count              = 2
  cluster_identifier = aws_neptune_cluster.main.id
  instance_class     = "db.r6g.large"
  engine             = "neptune"
 
  tags = { Name = "${var.project}-neptune-${count.index}" }
}

Solution 2: Ensure 2+ AZs in Subnet Group

# 
# Verify subnets span multiple AZs
data "aws_availability_zones" "available" {
  state = "available"
}
 
resource "aws_subnet" "private" {
  count             = 3  # 3 AZs for high availability
  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]
}

Solution 3: Add Security Group

# 
resource "aws_security_group" "neptune" {
  name   = "${var.project}-neptune"
  vpc_id = aws_vpc.main.id
 
  ingress {
    from_port       = 8182
    to_port         = 8182
    protocol        = "tcp"
    security_groups = [aws_security_group.app.id]
  }
 
  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

Troubleshooting Checklist

#
  1. ✅ Does the subnet group span at least 2 AZs?
  2. ✅ Is the subnet group created before the cluster?
  3. ✅ Are security groups allowing port 8182?
  4. ✅ Does the IAM role have the correct trust policy?
#

Conclusion

#

Neptune requires a subnet group spanning 2+ AZs, proper security groups (port 8182), and correctly configured parameter groups. Use explicit resource references instead of name strings, and add depends_on when Terraform can't infer the dependency automatically.

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

Share this article

Related articles