How to fix Error: Error creating API Gateway: NotFoundException in Terraform

TerraformINTERMEDIATEMEDIUMUpdated Dec 31, 2025· 111 views

Terraform's NotFoundException error when creating API Gateway resources typically occurs when you're trying to reference a REST API that doesn't exist yet, have missing dependencies, or are experiencing a race condition. Resolve it by adding explicit dependencies, using proper resource references, and ensuring your state is synchronized.

Quick fix

Fixes NotFoundException

resource "aws_api_gateway_rest_api" "example" {
  name        = "my-api"
  description = "My REST API"
}

resource "aws_api_gateway_resource" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  parent_id   = aws_api_gateway_rest_api.example.root_resource_id
  path_part   = "users"
}

resource "aws_api_gateway_method" "example" {
  rest_api_id      = aws_api_gateway_rest_api.example.id
  resource_id      = aws_api_gateway_resource.example.id
  http_method      = "GET"
  authorization    = "NONE"

  depends_on = [aws_api_gateway_resource.example]
}

resource "aws_api_gateway_integration" "example" {
  rest_api_id      = aws_api_gateway_rest_api.example.id
  resource_id      = aws_api_gateway_resource.example.id
  http_method      = aws_api_gateway_method.example.http_method
  type             = "HTTP"
  uri              = "https://example.com"

  depends_on = [aws_api_gateway_method.example]
}

resource "aws_api_gateway_deployment" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = "prod"

  depends_on = [aws_api_gateway_integration.example]
}
  1. Add explicit dependencies between API Gateway resources
  2. Verify resource references are correct
  3. Sync your Terraform state with AWS
  4. Use triggers to force redeployment when dependencies change
terraform — error
resource "aws_api_gateway_rest_api" "example" {
  name        = "my-api"
  description = "My REST API"
}
resource "aws_api_gateway_resource" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  parent_id   = aws_api_gateway_rest_api.example.root_resource_id
  path_part   = "users"
}
resource "aws_api_gateway_method" "example" {
  rest_api_id      = aws_api_gateway_rest_api.example.id
  resource_id      = aws_api_gateway_resource.example.id
  http_method      = "GET"
  authorization    = "NONE"
  depends_on = [aws_api_gateway_resource.example]
}
resource "aws_api_gateway_integration" "example" {
  rest_api_id      = aws_api_gateway_rest_api.example.id
  resource_id      = aws_api_gateway_resource.example.id
  http_method      = aws_api_gateway_method.example.http_method
  type             = "HTTP"
  uri              = "https://example.com"
  depends_on = [aws_api_gateway_method.example]
}
resource "aws_api_gateway_deployment" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = "prod"
  depends_on = [aws_api_gateway_integration.example]
}
Error: Error creating API Gateway: NotFoundException

What this error means

When Terraform attempts to create API Gateway resources (methods, integrations, deployments, or stages), it may fail with a NotFoundException if it tries to access a parent resource that doesn't exist or hasn't been fully provisioned yet. This happens most commonly when: 1. A child resource is created before its parent REST API is fully available 2. Resource references are incorrect or point to non-existent resources 3. Terraform's implicit dependency detection fails, causing out-of-order provisioning 4. Terraform state is out of sync with actual AWS resources 5. There's a race condition between resource creation and access The error can reference different missing resources: `aws_api_gateway_rest_api`, `aws_api_gateway_resource`, `aws_api_gateway_method`, or other API Gateway components.

Typical symptoms

  • Terraform apply fails during API Gateway resource creation with 'NotFoundException' error
  • Error message includes a reference to a missing REST API ID or resource ID
  • The same Terraform code works when run multiple times (race condition indicator)
  • Destroying and re-creating the infrastructure fixes the issue temporarily
  • Error occurs specifically on the first `terraform apply` or after clearing state
  • CI/CD pipelines fail intermittently when creating API Gateway resources

Common causes

  1. A resource depends on another that hasn't been created or fully propagated yet
  2. Missing explicit `depends_on` blocks between related API Gateway resources
  3. Incorrect resource ID references in your Terraform configuration
  4. Terraform state file is out of sync with actual AWS resources
  5. AWS API Gateway resources need time to propagate; Terraform moves too quickly
  6. Parent REST API is deleted or in an inconsistent state outside Terraform

How to fix "Error: Error creating API Gateway: NotFoundException"

1Add explicit dependencies between API Gateway resources

Most API Gateway NotFoundException errors occur because Terraform tries to create resources in the wrong order. Add explicit depends_on blocks to enforce proper sequencing:

hcl
resource "aws_api_gateway_rest_api" "example" {
  name        = "my-api"
  description = "My REST API"
}

resource "aws_api_gateway_resource" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  parent_id   = aws_api_gateway_rest_api.example.root_resource_id
  path_part   = "users"
}

resource "aws_api_gateway_method" "example" {
  rest_api_id      = aws_api_gateway_rest_api.example.id
  resource_id      = aws_api_gateway_resource.example.id
  http_method      = "GET"
  authorization    = "NONE"

  depends_on = [aws_api_gateway_resource.example]
}

resource "aws_api_gateway_integration" "example" {
  rest_api_id      = aws_api_gateway_rest_api.example.id
  resource_id      = aws_api_gateway_resource.example.id
  http_method      = aws_api_gateway_method.example.http_method
  type             = "HTTP"
  uri              = "https://example.com"

  depends_on = [aws_api_gateway_method.example]
}

resource "aws_api_gateway_deployment" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = "prod"

  depends_on = [aws_api_gateway_integration.example]
}

Notice how each resource explicitly declares its dependencies. This ensures Terraform creates them in the correct order.

2Verify resource references are correct

Check that all resource ID references are pointing to the correct resources. The most common mistake is using hardcoded IDs instead of Terraform references:

Wrong (hardcoded):

hcl
resource "aws_api_gateway_method" "example" {
  rest_api_id = "abc123def456"  # BAD: hardcoded ID
  resource_id = "xyz789"
  # ...
}

Correct (Terraform references):

hcl
resource "aws_api_gateway_method" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id  # GOOD
  resource_id = aws_api_gateway_resource.example.id
  # ...
}

Make sure:
- rest_api_id references the actual aws_api_gateway_rest_api resource
- resource_id references an aws_api_gateway_resource that exists
- parent_id correctly references the parent resource's ID
- All references use the correct resource type and attribute (usually .id)

3Sync your Terraform state with AWS

If your error persists, your Terraform state may be out of sync with actual AWS resources. Refresh the state:

bash
terraform refresh

This updates your local state file to match the actual resources in AWS. If the state is severely corrupted or if you need to start fresh:

bash
# Remove the problematic resource from state
terraform state rm aws_api_gateway_rest_api.example

# Then re-import it from AWS
terraform import aws_api_gateway_rest_api.example /restapis/abc123def456

You can find the REST API ID in the AWS Console under API Gateway, or via the CLI:

bash
aws apigateway get-rest-apis --region us-east-1
4Use triggers to force redeployment when dependencies change

For API Gateway deployments, use the triggers argument to ensure redeployment when underlying resources change:

hcl
resource "aws_api_gateway_deployment" "example" {
  rest_api_id = aws_api_gateway_rest_api.example.id
  stage_name  = "prod"

  triggers = {
    redeployment = sha1(jsonencode(aws_api_gateway_rest_api.example.body))
  }

  lifecycle {
    create_before_destroy = true
  }

  depends_on = [aws_api_gateway_integration.example]
}

The sha1 hash ensures that Terraform detects changes to the API definition and redeploys. The create_before_destroy lifecycle rule prevents temporary downtime.

5Check AWS region consistency

Ensure all your API Gateway resources are being created in the same AWS region. Mismatched regions can cause NotFoundException:

hcl
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "us-east-1"  # Ensure all resources use this region
}

# All resources below will use us-east-1
resource "aws_api_gateway_rest_api" "example" {
  name = "my-api"
  # region is inherited from provider
}

If you're managing multiple regions, explicitly set the provider for each resource:

hcl
resource "aws_api_gateway_rest_api" "example" {
  provider = aws.us_east_1
  name     = "my-api"
}
6Run terraform plan before apply

Always run terraform plan before terraform apply to preview resource creation order:

bash
terraform plan -out=plan.tfplan

Review the output to ensure resources are created in the expected order:
- REST API should be created first
- Resources should be created second
- Methods should be created third
- Integrations and deployments last

If the order looks wrong, add more explicit depends_on blocks. Then apply:

bash
terraform apply plan.tfplan

Advanced notes

Why explicit dependencies matter in API Gateway: AWS API Gateway has complex internal dependencies. While Terraform can infer some implicit dependencies through resource references, it cannot always detect all relationships, especially between deployments and their underlying resources. This is why explicit depends_on blocks are crucial.

Deployment lifecycle: API Gateway deployments are unique—they capture a snapshot of your API configuration at a point in time. If you modify methods, integrations, or resources after deployment, you must create a new deployment. Using triggers with a hash of the API definition ensures Terraform detects these changes automatically.

State file importance: API Gateway resources are complex and stateful. A corrupted or out-of-sync state file is a common source of NotFoundException errors. Always use a remote state backend (S3 + DynamoDB, Terraform Cloud, etc.) in production, never local state. This prevents state corruption and enables team collaboration.

Cross-module dependencies: If your API Gateway resources are split across multiple Terraform modules, ensure modules are explicitly ordered using depends_on at the root module level, not just within modules. Intra-module dependencies work reliably, but cross-module dependencies sometimes fail without explicit declaration.

API Gateway edge cases: Some API Gateway operations (like stage creation) can be slow to propagate through AWS's distributed system. If you're hitting race conditions even with depends_on, consider adding a small delay using null_resource with a local-exec provisioner, though this is a last resort.

Frequently asked questions

What does "NotFoundException" mean?
When Terraform attempts to create API Gateway resources (methods, integrations, deployments, or stages), it may fail with a NotFoundException if it tries to access a parent resource that doesn't exist or hasn't been fully provisioned yet. This happens most commonly when: 1. A child resource is created before its parent REST API is fully available 2.
How do I fix "NotFoundException"?
Terraform's NotFoundException error when creating API Gateway resources typically occurs when you're trying to reference a REST API that doesn't exist yet, have missing dependencies, or are experiencing a race condition. Resolve it by adding explicit dependencies, using proper resource references, and ensuring your state is synchronized.
What causes "NotFoundException"?
A resource depends on another that hasn't been created or fully propagated yet Missing explicit depends_on blocks between related API Gateway resources Incorrect resource ID references in your Terraform configuration
Is the "NotFoundException" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading