From d5e844975999b4348a2959f4492e8da001f726b5 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Wed, 9 Sep 2026 21:03:12 +0200 Subject: [PATCH 1/2] DOC-419: Document SIGILL crash on Apple Silicon with older VM guest kernels LocalStack Pro can exit immediately with exit code 252 (SIGILL) on newer Apple Silicon (e.g. M4) when running under Colima or Podman with an older Linux guest kernel, since the cryptography library (47.0.0+) uses ARM instructions those kernels don't fully support. Add the workaround (OPENSSL_armcap=0) and permanent fix (updating the guest kernel) to the startup troubleshooting FAQ, and cross-link it from the ARM64 support page's troubleshooting section. Co-Authored-By: Claude Sonnet 5 --- .../customization/advanced/arm64-support.md | 5 ++++ src/content/docs/aws/getting-started/faq.mdx | 24 +++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/src/content/docs/aws/customization/advanced/arm64-support.md b/src/content/docs/aws/customization/advanced/arm64-support.md index 089f9610..39451004 100644 --- a/src/content/docs/aws/customization/advanced/arm64-support.md +++ b/src/content/docs/aws/customization/advanced/arm64-support.md @@ -79,6 +79,11 @@ docker run --privileged --rm tonistiigi/binfmt --install amd64 ## Troubleshooting +### Container exits with SIGILL on Apple Silicon + +On newer Apple Silicon hardware (for example Apple M4), running under Colima or Podman with an older Linux guest kernel can cause the container to crash immediately after license activation with exit code `252` (SIGILL). +See [Why does the LocalStack container exit immediately with SIGILL (exit code 252) on Apple Silicon?](/aws/getting-started/faq/#why-does-the-localstack-container-exit-immediately-with-sigill-exit-code-252-on-apple-silicon) for the workaround and permanent fix. + ### Pulling images for other architectures :::note diff --git a/src/content/docs/aws/getting-started/faq.mdx b/src/content/docs/aws/getting-started/faq.mdx index d9eeba00..b90e8943 100644 --- a/src/content/docs/aws/getting-started/faq.mdx +++ b/src/content/docs/aws/getting-started/faq.mdx @@ -631,6 +631,30 @@ lsof -i :443 netstat -anv | grep 443 ``` +### Why does the LocalStack container exit immediately with SIGILL (exit code 252) on Apple Silicon? + +On newer Apple Silicon hardware (for example Apple M4), the container can crash immediately after license activation with exit code `252` (SIGILL, illegal instruction, reported as `-4` by some supervisors). +This is a known incompatibility between the `cryptography` library (version 47.0.0 and newer) and older Linux guest kernels running under Apple's Virtualization Framework: the library tries to use ARM CPU instructions the kernel does not fully support. +It mainly affects Colima or Podman with an older guest kernel (for example `6.8.0-39`); a fully updated Docker Desktop is generally not affected. + +**Workaround:** disable the faulty ARM capability detection by setting `OPENSSL_armcap=0` on the container: + +```yaml +services: + localstack: + image: localstack/localstack-pro:latest + environment: + - OPENSSL_armcap=0 +``` + +With `lstk`, set it as a `LOCALSTACK_`-prefixed host variable so `lstk start` forwards it into the container: + +```bash +LOCALSTACK_OPENSSL_armcap=0 lstk start +``` + +**Permanent fix:** update your VM provider (for example Colima) or its underlying Linux guest kernel to a newer version (for example `7.0.0`, or a patched `6.8.0`). + ### Why do I see a warning about non-prefixed `REQUESTS_CA_BUNDLE` being forwarded? The CLI prints `Non-prefixed environment variable REQUESTS_CA_BUNDLE is forwarded…` when it auto-forwards a host environment variable into the container. From 60da04b4af4a67f2b723ff87772e52edd1576832 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Wed, 9 Sep 2026 21:11:56 +0200 Subject: [PATCH 2/2] DOC-420: Document supervisor's fatal-signal decoding and faulthandler The supervisor no longer crashes silently on a fatal signal (previously only visible with DEBUG=1): it now unconditionally logs the decoded signal name and exit code, and enables Python's faulthandler by default so native crashes print a stack trace pointing at the offending import. Update the Apple Silicon SIGILL FAQ entry (DOC-419) with the message users will now actually see, and the faulthandler opt-out via PYTHONFAULTHANDLER. Co-Authored-By: Claude Sonnet 5 --- src/content/docs/aws/getting-started/faq.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/content/docs/aws/getting-started/faq.mdx b/src/content/docs/aws/getting-started/faq.mdx index b90e8943..0981bb53 100644 --- a/src/content/docs/aws/getting-started/faq.mdx +++ b/src/content/docs/aws/getting-started/faq.mdx @@ -637,6 +637,16 @@ On newer Apple Silicon hardware (for example Apple M4), the container can crash This is a known incompatibility between the `cryptography` library (version 47.0.0 and newer) and older Linux guest kernels running under Apple's Virtualization Framework: the library tries to use ARM CPU instructions the kernel does not fully support. It mainly affects Colima or Podman with an older guest kernel (for example `6.8.0-39`); a fully updated Docker Desktop is generally not affected. +The supervisor decodes and logs a fatal signal like this unconditionally, without needing `DEBUG=1`: + +```text +localstack process (PID 24) was terminated by signal 4 (SIGILL) (exit code 252). If there is no traceback above, the crash happened in native code, ... +``` + +It also enables Python's `faulthandler` in the `localstack` process by default (`PYTHONFAULTHANDLER=1`), so a native crash such as this one prints a Python and C stack trace before the process dies, for example pointing directly at the `cryptography` import. +Set `PYTHONFAULTHANDLER=0` yourself if you need to opt out. +Exit-code semantics are unchanged, the container still exits with the crashed process's status. + **Workaround:** disable the faulty ARM capability detection by setting `OPENSSL_armcap=0` on the container: ```yaml