Resolving Terraform AWS Provider Conflicts with LocalStack

Problem

You're developing locally with LocalStack, and everything seems configured correctly. Your Terraform code looks fine, but when you execute terraform plan or terraform apply, you get cryptic errors like:

Error: Unsupported argument
│ An argument named "codeconnections" is not expected here.

or

Error: Unsupported block type
│ Blocks of type "connection_arn" are not expected here.

The frustrating part is that your Terraform configuration doesn't even mention these fields. So where are these errors coming from?

Clarifying the Issue

The culprit is a mismatch between your Terraform AWS provider version and the provider overrides that LocalStack tools inject into your project.

When you use tflocal (LocalStack's Terraform wrapper), it automatically generates a file called localstack_providers_override.tf. This file contains provider configurations and resource definitions that are built for an older schema, specifically AWS Provider version 4.x.

This issue became prominent with LocalStack versions 2.0 and above, and it persists in recent releases including versions 3.x and 4.x. If you're using AWS Provider version 5.x, Terraform throws errors because the schema for certain resources has changed. For example, fields like codeconnections were renamed or restructured between major versions.

Here is a concrete example of the problematic code that tflocal often generates:

# Example of what tflocal generates (problematic for v5.x):
resource "aws_codestarconnections_connection" "example" {
  codeconnections = "github"  # ← This field doesn't exist in v5.x
}

Why It Matters

This version mismatch creates several problems that impact the development and deployment process:

• Misleading Errors: Terraform errors point to fields you never wrote, making debugging confusing and time-consuming.

• Silent Failures: The override file is generated automatically, so you might not realize it exists until errors appear.

• Development Friction: What should be a smooth local development experience becomes a troubleshooting session.

• CI/CD Inconsistency: This issue can also manifest in CI/CD pipelines if the pipeline's Terraform provider version differs from your local setup, leading to deployment failures that are hard to diagnose.

Key Terms

• LocalStack: A tool that emulates AWS services locally for development and testing.

• tflocal: A command-line wrapper that automatically configures Terraform to work with LocalStack.

• AWS Provider: The Terraform plugin that manages AWS resources.

• Provider Override: A configuration that modifies how Terraform providers behave.

• Schema Version: The structure and available fields for Terraform resources, which can change between provider versions.

Steps at a Glance

1. Identify the version conflict.

2. Choose a compatibility strategy.

3. Update your provider version constraints.

4. Clean up auto-generated files.

5. Verify the fix.

Detailed Steps

Step 1: Identify the Version Conflict

First, check your current Terraform and AWS provider versions by running:

terraform version

Next, look for the auto-generated override file:

ls -la | grep localstack

If localstack_providers_override.tf exists, you have confirmed the conflict.

Step 2: Choose Your Compatibility Strategy

Use this quick guide to decide on your approach:

Step 3: Update Provider Version Constraints

Option A: Lock to Provider v4.x (Recommended for Simplest Setup)

This ensures full compatibility with LocalStack overrides and is the most stable path for local development.

# versions.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.67.0"  # Last stable v4.x release
    }
  }
  required_version = ">= 1.0"
}

Option B: Upgrade to Provider v5.x and Manually Configure LocalStack

This option gives you access to the latest features. It requires you to manage your own LocalStack configuration and prevent the auto-generated override file.

First, ensure your versions.tf file is configured for v5.x.

# versions.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
  required_version = ">= 1.0"
}

Then, create a separate configuration file (e.g., localstack.tf) with your provider settings. You can find the full list of available service endpoints in the LocalStack documentation.

# localstack.tf
provider "aws" {
  region                      = "us-east-1"
  access_key                  = "test"
  secret_key                  = "test"
  # ... other settings
  endpoints {
    # Full list of endpoints
    s3      = "http://s3.localhost.localstack.cloud:4566"
    sqs     = "http://localhost:4566"
    lambda  = "http://localhost:4566"
    # ... etc.
  }
}

As an alternative to a configuration file, you can also set these endpoints and credentials using environment variables, which can be useful for CI/CD pipelines.

export AWS_ENDPOINT_URL=http://localhost:4566
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test

Step 4: Clean Up Auto-Generated Files

Remove any conflicting files and caches to ensure a clean start.

# Remove LocalStack override files
rm -f localstack_providers_override.tf
rm -f .localstack_providers_override.tf

Note: The .terraform.lock.hcl file locks provider versions to ensure consistent builds. When switching between strategies, removing this file forces Terraform to re-evaluate and download the correct provider version.

Step 5: Verify the Fix

Reinitialize and test to confirm that the fix is working.

# Clean Terraform state and lock file
rm -rf .terraform/
rm -f .terraform.lock.hcl

# Reinitialize Terraform to pull the correct provider version
terraform init

# Verify the provider version
terraform version

# Test with a plan
terraform plan

If you chose Option B, remember to use standard terraform commands instead of tflocal.

Conclusion

LocalStack is an excellent tool for local AWS development, but its automatic provider overrides can create version compatibility issues that are hard to debug. The key is to be intentional about your provider version strategy rather than letting tools make assumptions. For most teams, locking to AWS Provider v4.x provides the smoothest LocalStack experience. For teams needing cutting-edge features, manually managing your configuration with Provider v5.x offers more control.

---

Aaron Rose is a software engineer and technology writer at tech-reader.blog.