DEV Community

Peyton Green
Peyton Green

Posted on

LocalStack Broke Your Testcontainers Pipeline — Here's Every Fix Path

#python #testing #aws #docker

If you're here because your CI pipeline is throwing something like this:

RuntimeError: Unable to start LocalStack container.
LocalStack requires an account and auth token as of March 2026.
Set LOCALSTACK_AUTH_TOKEN in your environment to continue.
Enter fullscreen mode Exit fullscreen mode

You're not alone. LocalStack's auth requirement — announced quietly on March 23, 2026 — broke a lot of Testcontainers workflows overnight. The localstack/localstack Docker image now checks for a valid auth token on startup. If you don't have one, the container exits and your tests fail.

This post covers every fix path, ranked by how fast you can ship them. Some take five minutes. One takes two weeks but removes the problem permanently.

What Actually Changed

LocalStack's community image (localstack/localstack, the one almost everyone uses with Testcontainers) now requires LOCALSTACK_AUTH_TOKEN in the container environment. The Hobby tier is free, but it requires account creation. The paid plans start at $39/month.

Two things that are less bad than the initial reports suggested — and that most developers don't know yet:

1. CI credits are now unlimited on the free tier. The initial change included caps on CI usage that set off a second wave of outrage. LocalStack walked that back. As of now, the Hobby free tier has unlimited CI usage under a fair-use policy. If you're just running tests in GitHub Actions or GitLab CI, you're not hitting a hard cap.

2. There's a temporary bypass env var that works until April 6. LS_ACKNOWLEDGE_ACCOUNT_REQUIREMENT=1 disables the auth check in the current LocalStack version. This buys you time. It is explicitly time-limited — LocalStack has stated this bypass will stop working after April 6.

Neither of these makes the underlying situation okay if you object to vendor-gated infrastructure in your CI. But they change the urgency calculation on which fix path to take.

Fix Path 1: The April 6 Bypass (5 minutes, temporary)

If you need your pipeline green right now and can deal with the structural problem later, add this env var to your Testcontainers LocalStack configuration:

Python (testcontainers-python):

from testcontainers.localstack import LocalStackContainer

with LocalStackContainer(image="localstack/localstack:latest") \
        .with_env("LS_ACKNOWLEDGE_ACCOUNT_REQUIREMENT", "1") as localstack:
    # your tests
Enter fullscreen mode Exit fullscreen mode

Docker Compose:

services:
  localstack:
    image: localstack/localstack:latest
    environment:
      - LS_ACKNOWLEDGE_ACCOUNT_REQUIREMENT=1
      - SERVICES=s3,sqs,dynamodb
    ports:
      - "4566:4566"
Enter fullscreen mode Exit fullscreen mode

GitHub Actions:

- name: Start LocalStack
  run: docker run -d \
    -e LS_ACKNOWLEDGE_ACCOUNT_REQUIREMENT=1 \
    -e SERVICES=s3,sqs,dynamodb \
    -p 4566:4566 \
    localstack/localstack:latest
Enter fullscreen mode Exit fullscreen mode

Set a calendar reminder for April 5. This stops working April 6. If you use this path, you're taking on technical debt with a hard expiry date.

Fix Path 2: Pin to LocalStack 4.14.x (30 minutes, stable)

The last LocalStack version without the auth requirement is 4.14.x. Pinning your image tag stops the breakage and gives you a stable, auth-free LocalStack — at the cost of not receiving updates.

# Before:
with LocalStackContainer(image="localstack/localstack:latest") as localstack:

# After:
with LocalStackContainer(image="localstack/localstack:4.14") as localstack:
Enter fullscreen mode Exit fullscreen mode

Docker Compose:

services:
  localstack:
    image: localstack/localstack:4.14  # Last auth-free version
Enter fullscreen mode Exit fullscreen mode

The tradeoff is straightforward: you're frozen on a version that won't receive bug fixes or new service support. For most test suites that have been stable for a while, this is fine. For teams actively testing new AWS service features, it may not be.

This is a good bridge if you need to migrate properly but can't do it this week.

Fix Path 3: Create a Hobby Account and Use the Token (1 hour, stays on LocalStack)

If you want to stay on LocalStack and get the latest versions, create a free Hobby account at app.localstack.cloud, generate an auth token, and set it in your CI environment.

import os
from testcontainers.localstack import LocalStackContainer

with LocalStackContainer(image="localstack/localstack:latest") \
        .with_env("LOCALSTACK_AUTH_TOKEN", os.environ["LOCALSTACK_AUTH_TOKEN"]) as localstack:
    # your tests
Enter fullscreen mode Exit fullscreen mode

In GitHub Actions, add LOCALSTACK_AUTH_TOKEN as a repository secret, then:

- uses: LocalStack/setup-localstack@v0.2.3
  with:
    image-tag: latest
  env:
    LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

LocalStack has an official GitHub Action (setup-localstack) that handles the auth flow. This is the cleanest path if you're staying on LocalStack and are comfortable with the vendor dependency.

Caveat on free tier: The Hobby tier is non-commercial only. If your tests support a commercial product, review the terms — you may be on the paid tier.

Fix Path 4: Migrate to a Zero-Auth Alternative (1-5 days, removes the problem)

The options depend on what your tests actually need.

If your tests are Python and don't need a real running container

Moto is the right answer. It's MIT-licensed, no Docker, no auth, no daemon. It intercepts boto3 calls in-process.

pip install moto[s3,sqs,dynamodb]
Enter fullscreen mode Exit fullscreen mode 
from moto import mock_aws
import boto3

@mock_aws
def test_s3_round_trip():
    s3 = boto3.client("s3", region_name="us-east-1")
    s3.create_bucket(Bucket="test-bucket")
    s3.put_object(Bucket="test-bucket", Key="key", Body=b"value")
    result = s3.get_object(Bucket="test-bucket", Key="key")
    assert result["Body"].read() == b"value"
Enter fullscreen mode Exit fullscreen mode

200+ AWS services, pure Python, works in any test runner. See Testing Without the Subscription Tax: Part 1 for the full migration guide with conftest.py fixtures.

If your tests need a real running container (cross-service, network behavior, non-Python)

Floci is the drop-in LocalStack replacement that emerged this week. Port 4566 compatible — zero code changes if you were using localhost:4566 or the LOCALSTACK_HOST environment variable.

from testcontainers.core.container import DockerContainer
from testcontainers.core.waiting_utils import wait_for_logs

class FlociContainer(DockerContainer):
    def __init__(self):
        super().__init__("ghcr.io/floci/floci:latest")
        self.with_exposed_ports(4566)

    def get_url(self):
        host = self.get_container_host_ip()
        port = self.get_exposed_port(4566)
        return f"http://{host}:{port}"

with FlociContainer() as floci:
    endpoint = floci.get_url()
    s3 = boto3.client(
        "s3",
        endpoint_url=endpoint,
        aws_access_key_id="test",
        aws_secret_access_key="test",
        region_name="us-east-1"
    )
    # your tests, zero code changes beyond the endpoint
Enter fullscreen mode Exit fullscreen mode

Floci is new (v1.0.5, released March 23, 2026 — the same day as LocalStack's change) and has known gaps. Six open functional bugs: OIDC, CDK Lambda encoding, S3 objects over 27MB, Ruby Lambda runtime, SQS JSON 1.0 routing, and HeadObject lastModified precision. Counter-signal: 10 releases in 8 days, 6 external-contributor PRs open, GitHub stars went from 887 to 1,500 while the HN skeptic thread was live. Adoption is running faster than the criticism.

If any of those six gap areas are in your test suite, test against Floci specifically before committing to it. If they're not, it's the closest thing to a zero-auth LocalStack drop-in that exists right now.

Existing LocalStack article for full Floci setup with docker-compose: LocalStack Now Requires an Account — Here's How to Test AWS in Python Without One

Which Path Is Right for You

Situation Recommended path
Need CI green in the next hour Fix Path 1 (bypass env var) — set April 5 reminder
Stable test suite, want minimal change Fix Path 2 (pin 4.14.x)
Happy with LocalStack, comfortable with vendor account Fix Path 3 (Hobby account + token)
Python tests, no container needed Fix Path 4 → Moto
Need container, multi-service, or non-Python Fix Path 4 → Floci
Java / JVM Testcontainers Fix Path 2 or 3 now; Floci Java support is in progress

The Broader Pattern

This is the third time in eighteen months that a dev infrastructure vendor has changed their free tier in a way that breaks existing pipelines. The failure mode is always the same: the tool becomes load-bearing infrastructure, adoption metrics justify monetization pressure, the free tier changes, your CI breaks at the worst possible time.

LocalStack's Hobby tier is still genuinely free for non-commercial use. The auth requirement isn't unreasonable from a business perspective. But the pattern — vendor-gated infrastructure in your test suite — is worth thinking about for the long run. moto and SAM Local exist. Floci now exists. The zero-auth path is still available.

If this helped: The Automation Cookbook for Python Developers covers a broader set of automation and testing patterns — including pytest fixture organization, retry logic, and scheduling automation scripts. It's the practical follow-on to the articles in this series.

Top comments (0)