lstk FAQ & Troubleshooting

FAQ

Can I use lstk with Docker Compose?

You can use lstk with Docker Compose for the commands that talk to an already-running emulator. lstk start, lstk stop, and the other lifecycle commands manage the container that lstk itself runs, and they reject --endpoint-url. If you run LocalStack from a docker-compose.yml, you can still use the emulator-facing commands lstk az and lstk status against it: pass --endpoint-url <url>, or set LSTK_ENDPOINT_URL, to target the Compose deployment.

See Targeting an external emulator for the commands that accept an endpoint, and the Docker Compose installation guide for the Compose setup itself.

Which Docker image does lstk use?

It depends on the emulator type configured in your config.toml. The Azure emulator uses localstack/localstack-azure, and needs an auth token whose license covers Azure. To pull it from somewhere else, such as an internal registry mirror, set image. See Emulator types.

How do I pass configuration options like DEBUG to the container?

Use environment profiles in your config.toml. Define the variables under an [env.<name>] section and reference that name in the env list of your container config. See Passing environment variables to the container for details.

How do I save and restore emulator state?

The Azure emulator doesn’t support snapshots or persistence yet; both features are available for the AWS emulator only. The Azure emulator doesn’t implement the state API that snapshots rely on, so lstk save and lstk load print a warning that snapshot support for Azure is experimental and then fail with a 404 error from the emulator. lstk start --persist is accepted, but the emulator still starts without any of your resources after every restart.

How do I pin a specific LocalStack version?

The Azure emulator image has no version tags yet, so you can’t pin a specific release with the tag field. The localstack/localstack-azure image is published with the latest and dev tags only, plus their -amd64 and -arm64 variants. To keep using a build you’ve tested, copy the image to your own registry and point image at that copy:

[[containers]]
type  = "azure"
image = "registry.internal.example.com/localstack/localstack-azure:tested"
port  = "4566"

Troubleshooting

Port 443 already in use

By default, LocalStack publishes both port 4566 and port 443 (controlled by the GATEWAY_LISTEN variable). On some machines, another program, such as a local web server or an ingress proxy, already uses port 443.

Because port 443 comes from the default GATEWAY_LISTEN, a busy 443 is not fatal: lstk starts the emulator without that port and prints a warning:

> Warning: Port 443 is in use — starting without it. Clients that hardwire HTTPS on port 443 must use https://localhost:4566 instead (the edge port serves both HTTP and HTTPS).

You only need to act if you want to silence the warning.

To skip port 443 entirely, set GATEWAY_LISTEN to :4566, so the emulator listens on port 4566 only:

[[containers]]
type = "azure"
tag  = "latest"
port = "4566"
env  = ["nossl"]

[env.nossl]
GATEWAY_LISTEN = ":4566"

Without a host part, lstk publishes the port on 127.0.0.1 only. The host part of the first entry sets the address that the ports are published on, so a value such as 0.0.0.0:4566 makes the emulator reachable from other machines.

Note

A port you list explicitly in a custom GATEWAY_LISTEN is treated as a hard requirement, so a busy one there fails the start with Port 443 is already in use rather than being dropped. Only the 443 from the default value is best-effort.

Docker is not running

lstk requires a running Docker daemon. If Docker is not reachable, you see an error like this one, here from a Linux machine:

Error: Docker is not available
  cannot connect to Docker daemon: ...
  ==> Start Docker: sudo systemctl start docker
  ==> Install Docker: https://docs.docker.com/get-docker/

Fix: Start your container runtime. lstk works with Docker Desktop, Rancher Desktop, Colima, OrbStack, Lima, and Podman, and its error message suggests the start command for the runtime it detects, for example rdctl start for Rancher Desktop, colima start for Colima, or podman machine start for Podman. You can also point lstk at a specific socket with DOCKER_HOST. See Container runtime discovery for how the daemon is located.

Authentication required in non-interactive mode

When running without a TTY (e.g. in CI), lstk cannot open a browser for login. If no token is found in the keyring or environment, it fails:

authentication required: set LOCALSTACK_AUTH_TOKEN or run in interactive mode

Fix: Set the LOCALSTACK_AUTH_TOKEN environment variable before running lstk:

export LOCALSTACK_AUTH_TOKEN=<your-token>
lstk --non-interactive start

You can find your auth token on the Auth Tokens page.

License validation failed

The Azure emulator validates your license itself when it starts. If your auth token is invalid, expired, or not linked to an active license, the container exits, and lstk reports the exit code and shows the emulator’s reason. When a license file cached by an earlier lstk run exists, lstk first deletes it and retries the start once, so the error follows a warning:

> Warning: License rejected at startup — refreshing the cached license and retrying
Starting LocalStack...
Error: LocalStack exited unexpectedly (exit code 55)
...
License activation failed! 🔑❌

Reason: The credentials defined in your environment are invalid. Please make sure to set the LOCALSTACK_AUTH_TOKEN variable to a valid auth token. You can find your auth token in the LocalStack web app https://app.localstack.cloud.

Fix:

• Verify your token is valid at the Auth Tokens page.
• If you pass the token in LOCALSTACK_AUTH_TOKEN, set the variable to a valid token.
• If you logged in with lstk login, run lstk logout and then lstk login again. While a token is stored, lstk login only reports that you’re already logged in.
• Make sure your license covers LocalStack for Azure.

Image pull failed

If lstk cannot pull the Docker image, check your network connection and Docker configuration. On corporate networks, you may need to configure Docker’s proxy settings, see How do I configure LocalStack to use my corporate HTTP and HTTPS proxy?.

Unknown environment profile

If your container config references an env profile that doesn’t exist, lstk returns:

environment "myprofile" referenced in container config not found

Fix: Make sure the profile name in the env list matches an [env.<name>] section in your config.toml:

[[containers]]
type = "azure"
env  = ["myprofile"]   # must match the section name below

[env.myprofile]
DEBUG = "1"

lstk az says the Azure CLI integration is not set up

lstk az runs the Azure CLI in its own config directory, which lstk setup azure prepares. Until you run it, lstk az fails with:

Error: Azure CLI integration is not set up
  ==> Set it up: lstk setup azure

Fix: Start the emulator, then run lstk setup azure once.

lstk az fails with a DNS error

The Azure emulator serves its endpoints under *.localhost.localstack.cloud, and lstk az stops with DNS resolution required for 'lstk az' when those names don’t resolve to 127.0.0.1. Some routers and DNS resolvers block names that resolve to a loopback address, as a protection against DNS rebinding.

Fix: Make sure that names under *.localhost.localstack.cloud resolve to 127.0.0.1, for example by allowing localhost.localstack.cloud in your resolver’s rebinding protection. lstk doctor network checks whether localhost.localstack.cloud resolves.

Getting help

If the steps above don’t resolve your issue, email support@localstack.cloud with details of what you’re seeing.