lstk FAQ & Troubleshooting

FAQ

Can I use lstk with Docker Compose?

No. lstk manages its own Docker container directly. If you use a docker-compose.yml to run LocalStack, you do not need lstk, and vice versa. Do not mix lstk start with a Docker Compose setup; they are separate, independent methods.

For Docker Compose configuration, see the Docker Compose installation guide.

Which Docker image does lstk use?

It depends on the emulator type configured in your config.toml. The AWS emulator uses localstack/localstack-pro, the Snowflake emulator uses localstack/snowflake, and the Azure emulator uses localstack/localstack-azure. All require a valid auth token (including the free Hobby tier). See Emulator types.

How do I pass configuration options like DEBUG or PERSISTENCE 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?

Use lstk snapshot save to capture the running AWS emulator’s state to a local file or a Cloud Pod, and lstk snapshot load (or the lstk save / lstk load aliases) to restore it. To drop in-memory state without writing a snapshot, use lstk reset (AWS emulator only).

How do I pin a specific LocalStack version?

Set the tag field in your config.toml to a specific version tag:

[[containers]]
type = "aws"
tag  = "2026.4"
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 systems port 443 is already taken — Windows with Hyper-V, IIS, or VPN software, or an ingress proxy such as Rancher Desktop’s Traefik.

Because port 443 comes from the default GATEWAY_LISTEN, a busy 443 is not fatal: lstk drops that publication with a warning and starts anyway, and HTTPS is still served on the edge port 4566. You only need to act if you want to silence the warning or bind 443 elsewhere.

To skip port 443 entirely, override GATEWAY_LISTEN to bind only to 4566:

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

[env.nossl]
GATEWAY_LISTEN = "0.0.0.0:4566"

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 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 will see an error like:

Error: runtime not healthy

Fix: Start your container runtime. lstk works with Docker Desktop, Rancher Desktop, Colima, OrbStack, Lima, and Podman — start the Docker daemon (sudo systemctl start docker on Linux) or the relevant VM (rdctl start, colima start, podman machine start, …). When the runtime is unavailable, lstk’s error tailors its suggested start command to whichever runtime it detects. 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

If your auth token is invalid, expired, or not linked to an active license, the LocalStack container exits with a license error:

The license activation failed for the following reason:
No credentials were found in the environment.

Fix:

• Verify your token is valid at the Auth Tokens page.
• Make sure the token is set correctly, either via lstk login or the LOCALSTACK_AUTH_TOKEN environment variable.
• A stale token or cached license no longer requires a manual lstk logout: when the platform definitively rejects it, lstk drops the cached license and, in an interactive terminal, prompts you to log in again and retries automatically. In non-interactive mode, run lstk logout && lstk login (or set a valid LOCALSTACK_AUTH_TOKEN) and re-run.

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 = "aws"
env  = ["myprofile"]   # must match the section name below

[env.myprofile]
DEBUG = "1"

Getting help

If the steps above don’t resolve your issue, see Get Help for the available support channels, including the support email and in-app chat.