Bug: AWS SAM CLI is unable to process a Terraform project that uses an OpenAPI specification

[IlyesDemineExtVeolia]

Description:

Error: AWS SAM CLI is unable to process a Terraform project that uses an OpenAPI specification to define the API Gateway resource. AWS SAM CLI does not currently support this functionality.

Steps to reproduce:

Command to reproduce : sam build

Running Prepare Hook to prepare the current application                                                                                                                                                                            
Executing prepare hook of hook "terraform"                                                                                                                                                                                         
Initializing Terraform application                                                                                                                                                                                                 
..............................
Creating terraform plan and getting JSON output                                                                                                                                                                                    
.....................................................................................................................................................................................................................................
Generating metadata file                                                                                                                                                                                                           
                                                                                                                                                                                                                                   
Unresolvable attributes discovered in project, run terraform apply to resolve them.                                                                                                                                                
                                                                                                                                                                                                                                   
                                                                                                                                                                                                                                   
Experimental features are enabled for this session.                                                                                                                                                                                
Visit the docs page to learn more about the AWS Beta terms https://aws.amazon.com/service-terms/.                                                                                                                                  
                                                                                                                                                                                                                                   
Error: AWS SAM CLI is unable to process a Terraform project that uses an OpenAPI specification to define the API Gateway resource. AWS SAM CLI does not currently support this functionality. Affected resource: module.api_gateway_test.aws_apigatewayv2_api.this.

samconfig.toml :

version = 0.1
[default]
[default.build.parameters]
hook_name = "terraform"
beta_features = true

apigateway-v2 Terraform :

module "api_gateway_test" {
  source  = "terraform-aws-modules/apigateway-v2/aws"
  version = "2.2.2"

  name          = "${local.project_name_api}-${var.env_name}"
  protocol_type = "HTTP"

  create_api_domain_name = false

  cors_configuration = {
    allow_headers = ["*"]
    allow_methods = ["GET", "POST", "PATCH", "PUT", "DELETE", "OPTIONS"]
    allow_origins = [var.site_origin]
  }

  # Access logs
  default_stage_access_log_destination_arn = aws_cloudwatch_log_group.api_logs_actiflo.arn
  default_stage_access_log_format          = "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId $context.integrationErrorMessage"


  # Routes and integrations
  integrations = {
    "GET /api/v1.0/consumption/chemicals/description/kpis" = {
      lambda_arn             = module.lambda_chemical_description.lambda_function_arn
      payload_format_version = "1.0"
      timeout_milliseconds   = 29000
      authorizer_key         = "cognito"
      authorization_type     = "JWT"
    }
  }

  authorizers = {
    "cognito" = {
      authorizer_type  = "JWT"
      identity_sources = "$request.header.Authorization"
      name             = "cognito"
      audience         = [var.cognito_app_client_id_angular_performance, var.cognito_app_client_id_angular_essential, var.cognito_app_client_id_angular_backoffice]
      issuer           = "https://cognito-idp.eu-west-1.amazonaws.com/${var.cognito_id}"
    }
  }

  tags = {
    ProductModule    = "test"
  }
}

Observed result:

Expected result:

Additional environment details (Ex: Windows, Mac, Amazon Linux etc)

1. OS: Mac os m1 Sonoma 14.0
2. sam --version: 1.103.0
3. AWS region: eu-west-1
4. Terraform : 1.4.6

# Paste the output of `sam --info` here

Add --debug flag to command you are running

[mildaniel]

Hey @IlyesDemineExtVeolia, thanks for creating this issue. There are some limitations with what the Terraform plan file produces before an application is applied, one of those being the OpenAPI spec.

As a workaround, you can run a terraform apply to deploy your resources first, and then use the build and local commands as intended.

[IlyesDemineExtVeolia]

Thanks for your response. I will try your solution 🙂

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.

[codinronan]

For anyone who runs across this in 2025:

The specific technical issue is a limitation of terraform plan. It needs the resources deployed so it can resolve what OpenAPI actually did.

However, the real issue is that HttpApi (API Gateway v2) is not supported in the SAM CLI to run locally (sam local start-api). There's alot of reasons for this, and they are good ones. It's a rough problem to solve.

I actually PREFER to use v1, so I am replacing my infra to use APIGW REST apis instead of Http APIs, which run fine in sam local.