Learn LocalStack - Performance & Troubleshooting

#Introduction

In episode 18 we deployed LocalStack to CI and the pipeline runs automatically. But when something gets stuck — Lambda not invoked, port collision, lost state — debugging skills are what decide the outcome. This episode closes Phase 5 with Performance & Troubleshooting: how to read logs, check health, monitor resources, and solve the most common problems. This isn't theory — it's a checklist you'll use almost every day.

#Logging: localstack logs & DEBUG=1

By default, LocalStack's logs are fairly quiet. For investigation, enable debug mode at startup:

DEBUG=1 localstack start

Or via environment variables on the container:

docker run -d --name ls-debug -e DEBUG=1 -p 4566:4566 localstack/localstack:stable

View the logs with:

localstack logs
docker logs -f ls-debug

With DEBUG=1, every request is recorded in full, including status and its trace. Turn it off when not needed — debug mode produces a huge amount of logs and slows the instance down slightly.

#Health Endpoint: /_localstack/health

The fastest way to confirm a service is alive is the health endpoint:

curl -s http://localhost:4566/_localstack/health

The response is JSON containing the status of each service:

{
  "services": {
    "s3": "running",
    "dynamodb": "running",
    "lambda": "available",
    "iam": "available"
  }
}

running means the service is active; available means it's ready to activate on first call; while error or stopped indicates a problem. This endpoint is very useful as a readiness check in CI or an orchestrator — we also used it in episode 18.

#Monitoring Docker Resources

LocalStack runs on top of a container, so the primary monitoring tool is Docker:

docker stats --no-stream localstack
docker stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}\t{{.CPUPerc}}"

If memory spikes, check how many services are active and narrow them down via SERVICES:

SERVICES=s3,dynamodb,lambda localstack start

Fewer active services means fewer processes and less memory used. A bloated persistence volume can also be measured:

docker exec localstack du -sh /var/lib/localstack

#Common Problem 1: Port 4566 Conflict

The classic error: port 4566 is already in use. The cause is an old instance still running, or another process attached to the port. Detect it with:

lsof -i :4566
docker ps

Then clean up the old instance:

localstack stop
docker rm -f localstack

An alternative: run on a different port — exactly like the per-developer isolation strategy from episode 15.

#Common Problem 2: Lambda Not Invoked

A Lambda that doesn't respond is usually caused by one of these:

The first step is always the same: enable DEBUG=1, then run awslocal lambda invoke. Errors inside the function code will appear in the logs with a full traceback or stack trace. Also make sure LAMBDA_EXECUTOR points to a mode supported by your environment (e.g. Docker).

#Common Problem 3: Lost Persistence

Persistence not working is usually caused by one of these:

• PERSISTENCE=1 wasn't set when the instance was first created.
• The Docker volume isn't mounted, so the new instance starts empty.
• Running via docker run without the -v argument.

Check the data location and the mounted volume:

docker exec localstack ls /var/lib/localstack
docker inspect localstack --format '{{.Mounts}}'

If the folder is empty, persistence was never active. The fix: restart the instance with PERSISTENCE=1 and a named volume like the example in episode 15.

#Common Problem 4: Image Version Mismatch

A CLI and image on different versions often produce weird behavior. Make sure both are in sync:

localstack --version
docker pull localstack/localstack:stable
localstack status

The stable tag always points to the latest stable release. After upgrading, check the changelog — some releases change default behavior that can break assumptions in old code.

#Service Limitations to Anticipate

Many "problems" are actually deliberate emulation limits:

• IAM and security are only partially emulated, as we discussed in episode 14.
• Some Pro features like AWS Replicator and Cloud Pods require a license.
• Some services return mock data rather than full behavior.
• Parity changes between versions — always retest after upgrading the image.

The best way to know what's supported: read the official per-service documentation or the release changelog. If a feature isn't available, the alternative is testing directly on a real AWS account.

#Closing

LocalStack troubleshooting checklist:

• Enable DEBUG=1 and read localstack logs for unclear symptoms.
• Use /_localstack/health as a readiness check.
• Monitor memory via docker stats and limit services with SERVICES.
• Port conflict: detect with lsof -i :4566, then clean up old instances.
• Lost persistence: check PERSISTENCE and the volume mount.
• Always keep the CLI and image versions in sync.

With Phase 5 complete, we have a solid foundation: from networking, security, and advanced services to CI/CD and debugging. In the next episode 20 we discuss the latest stable 2026.x features: calendar versioning, the single Community and Pro image, and the 2026.07.0 release highlights. See you there!