Skip to content

fix: don't forward host LOCALSTACK_* env that clobbers container PATH#379

Closed
gtsiolis wants to merge 1 commit into
mainfrom
devx-984-lstk-exits-unexpectedly-with-mkdir-command-not-found-d358
Closed

fix: don't forward host LOCALSTACK_* env that clobbers container PATH#379
gtsiolis wants to merge 1 commit into
mainfrom
devx-984-lstk-exits-unexpectedly-with-mkdir-command-not-found-d358

Conversation

@gtsiolis

@gtsiolis gtsiolis commented Jul 9, 2026

Copy link
Copy Markdown
Member

Note: This overlaps heavily with the pre-existing draft #378 (same root cause, same filterHostEnv blocklist approach). Opened independently before I saw #378. Reviewers should treat these as alternatives — either merge one, or fold the two additions this PR has (below) into #378. Happy to close this in favor of #378.

Problem

lstk start crashed immediately with:

LocalStack exited unexpectedly:
/usr/local/bin/docker-entrypoint.sh: line 22: mkdir: command not found

mkdir: command not found means the container's PATH was empty when the entrypoint ran.

Root cause

LocalStack's docker-entrypoint.sh re-exports every LOCALSTACK_<NAME> variable as <NAME> (stripping the prefix) via a line-oriented source <(env | … | sed …), and does not set PATH itself — it relies on the image's own ENV PATH.

Since #161, lstk forwards all host LOCALSTACK_* variables into the container verbatim (filterHostEnv). So a host LOCALSTACK_PATH became export PATH=… inside the container, blanking PATH. The entrypoint's very next command (mkdir -p /var/lib/localstack/logs) then failed with mkdir: command not found and the emulator exited on startup — independent of config file and image tag, matching the report.

Fix

filterHostEnv now drops:

  • LOCALSTACK_* variables whose entrypoint-stripped name is a reserved shell variable (PATH, HOME, SHELL, IFS, ENV, BASH_ENV, LD_PRELOAD, LD_LIBRARY_PATH, PYTHONPATH, PYTHONHOME); and
  • any value containing a newline/carriage return, which could inject spurious export lines through the entrypoint's line-oriented pipeline (a second, distinct way to blank PATH).

LOCALSTACK_AUTH_TOKEN filtering and normal CI / LOCALSTACK_* forwarding are unchanged.

Compared to #378, this PR additionally: (1) sanitizes newline/CR values, and (2) covers a slightly wider reserved set. #378 additionally emits a user-facing warning for each dropped var, which is a nice touch this PR lacks and worth keeping.

Tests

  • Unit: TestFilterHostEnv now asserts LOCALSTACK_PATH, other reserved-name vars, and newline-containing values are not forwarded.
  • Integration: TestStartCommandIgnoresPathClobberingHostEnv starts the emulator with LOCALSTACK_PATH set and asserts it comes up healthy (fails with the mkdir: command not found crash before the fix). Needs Docker + LOCALSTACK_AUTH_TOKEN, so it runs in CI.

Separately worth filing upstream: excluding PATH and friends from prefix-stripping in the image entrypoint itself, which would also protect compose users who export LOCALSTACK_PATH without lstk involved.

… (DEVX-984)

LocalStack's docker-entrypoint.sh re-exports every LOCALSTACK_<NAME>
variable as <NAME> (stripping the prefix) and relies on the image's own
PATH. lstk forwarded all host LOCALSTACK_* variables verbatim, so a host
LOCALSTACK_PATH became `export PATH=...` inside the container, blanking
PATH — and the entrypoint's next command (`mkdir -p ...`) failed with
"mkdir: command not found", crashing the emulator on startup.

filterHostEnv now drops LOCALSTACK_* variables whose entrypoint-stripped
name is a reserved shell variable (PATH, HOME, LD_PRELOAD, ...) and any
value containing a newline/carriage return (which could inject spurious
export lines through the entrypoint's line-oriented pipeline).

Generated with [Linear](https://linear.app/localstack/issue/DEVX-984/lstk-exits-unexpectedly-with-mkdir-command-not-found#agent-session-dc304e8b)

Co-authored-by: linear-code[bot] <222613912+linear-code[bot]@users.noreply.github.com>
gtsiolis added a commit that referenced this pull request Jul 9, 2026
…ocklist (DEVX-984)

Folds in the two improvements from #379: a multi-line value is split by
the entrypoint's line-oriented env pipeline and can inject rogue exports
(e.g. an embedded 'LOCALSTACK_PATH=' line blanks PATH), and IFS/SHELL/
ENV/BASH_ENV join the reserved set (the entrypoint sources the stripped
exports mid-script, so IFS corrupts its word splitting). Unlike #379,
both drops surface a warning instead of happening silently.
@gtsiolis

gtsiolis commented Jul 9, 2026

Copy link
Copy Markdown
Member Author

Closing in favor of #378.

@gtsiolis gtsiolis closed this Jul 9, 2026
@gtsiolis gtsiolis deleted the devx-984-lstk-exits-unexpectedly-with-mkdir-command-not-found-d358 branch July 9, 2026 15:02
gtsiolis added a commit that referenced this pull request Jul 9, 2026
…ocklist (DEVX-984)

Folds in the two improvements from #379: a multi-line value is split by
the entrypoint's line-oriented env pipeline and can inject rogue exports
(e.g. an embedded 'LOCALSTACK_PATH=' line blanks PATH), and IFS/SHELL/
ENV/BASH_ENV join the reserved set (the entrypoint sources the stripped
exports mid-script, so IFS corrupts its word splitting). Unlike #379,
both drops surface a warning instead of happening silently.

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant