Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

fix(lambda): override AWS_ENDPOINT_URL after function env vars (#336)

Jay Janssena2f2842cecfd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b7ed892d..d43082f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ Versioning follows [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Fixed
+- **Lambda endpoint URL override** — function-level `AWS_ENDPOINT_URL` environment variables no longer override MiniStack's internal endpoint. When MiniStack runs in Docker with a host-port that differs from the container port (e.g., `4568:4566`), Lambda functions would receive the host-mapped URL which is unreachable from inside the container, causing SDK callbacks to fail with "connection refused". Fix applies to all executor paths: provided runtime, Docker mode, image mode, and warm workers. Contributed by @jayjanssen
- **SFN callback/activity timeout not scaled** — `SFN_WAIT_SCALE=0` no longer causes `States.Timeout` on activity tasks and `waitForTaskToken` callbacks. The scale factor was incorrectly applied to functional timeouts (which must wait for real work to complete), not just Wait state sleeps and retry intervals. Contributed by @jayjanssen
---
diff --git a/ministack/core/lambda_runtime.py b/ministack/core/lambda_runtime.py
index 93996da4..d1cbd12c 100644
--- a/ministack/core/lambda_runtime.py
+++ b/ministack/core/lambda_runtime.py
@@ -405,6 +405,12 @@ class Worker:
module_name, handler_name = handler.rsplit(".", 1)
env_vars = self.config.get("Environment", {}).get("Variables", {})
spawn_env = {**os.environ, **env_vars}
+ # Restore the internal endpoint URL so Lambda SDK calls reach
+ # this MiniStack instance, not a host-mapped port that may be
+ # unreachable from inside the container.
+ for key in ("AWS_ENDPOINT_URL", "LOCALSTACK_HOSTNAME"):
+ if key in os.environ:
+ spawn_env[key] = os.environ[key]
spawn_env.setdefault("LAMBDA_TASK_ROOT", code_dir)
spawn_env.setdefault("AWS_LAMBDA_FUNCTION_NAME", self.config.get("FunctionName", ""))
spawn_env.setdefault("AWS_LAMBDA_FUNCTION_MEMORY_SIZE", str(self.config.get("MemorySize", 128)))
diff --git a/ministack/services/lambda_svc.py b/ministack/services/lambda_svc.py
index f567a1b2..6ae0a9d3 100644
--- a/ministack/services/lambda_svc.py
+++ b/ministack/services/lambda_svc.py
@@ -1152,6 +1152,10 @@ def _execute_function_docker(func: dict, event: dict) -> dict:
else:
container_env["LAMBDA_TASK_ROOT"] = "/var/task"
container_env["_HANDLER"] = handler
+ container_env.update(env_vars)
+ # Override AWS_ENDPOINT_URL *after* function env vars so the
+ # Lambda container always calls back to this MiniStack
+ # instance, not a host-mapped port.
endpoint = _normalize_endpoint_url(os.environ.get("AWS_ENDPOINT_URL", ""))
if not endpoint:
endpoint = _normalize_endpoint_url(env_vars.get("AWS_ENDPOINT_URL", ""))
@@ -1159,7 +1163,6 @@ def _execute_function_docker(func: dict, event: dict) -> dict:
endpoint = _normalize_endpoint_url(env_vars.get("LOCALSTACK_HOSTNAME", ""))
if endpoint:
container_env["AWS_ENDPOINT_URL"] = endpoint
- container_env.update(env_vars)
event_file = os.path.join(code_dir, "_event.json")
with open(event_file, "w") as ef:
@@ -1403,12 +1406,14 @@ def _execute_function_image(func: dict, event: dict) -> dict:
"AWS_LAMBDA_FUNCTION_VERSION": config.get("Version", "$LATEST"),
"AWS_LAMBDA_LOG_STREAM_NAME": new_uuid(),
}
+ container_env.update(env_vars)
+ # Override AWS_ENDPOINT_URL *after* function env vars so the
+ # Lambda container always calls back to this MiniStack instance.
endpoint = _normalize_endpoint_url(os.environ.get("AWS_ENDPOINT_URL", ""))
if not endpoint:
endpoint = _normalize_endpoint_url(env_vars.get("AWS_ENDPOINT_URL", ""))
if endpoint:
container_env["AWS_ENDPOINT_URL"] = endpoint
- container_env.update(env_vars)
run_kwargs = {
"image": image_uri,
@@ -1601,7 +1606,12 @@ def _execute_function_provided(func: dict, event: dict) -> dict:
"LAMBDA_TASK_ROOT": code_dir,
"_HANDLER": config.get("Handler", "bootstrap"),
})
- # Pass through AWS_ENDPOINT_URL for SDK calls
+ proc_env.update(env_vars)
+ # Override AWS_ENDPOINT_URL *after* function env vars so
+ # Lambda binaries always call back to this MiniStack
+ # instance. Function-level env vars may carry the
+ # host-mapped URL which is unreachable from inside the
+ # container.
endpoint = os.environ.get("AWS_ENDPOINT_URL", "")
if not endpoint:
hostname = os.environ.get("LOCALSTACK_HOSTNAME", "")
@@ -1609,7 +1619,6 @@ def _execute_function_provided(func: dict, event: dict) -> dict:
endpoint = _normalize_endpoint_url(hostname)
if endpoint:
proc_env["AWS_ENDPOINT_URL"] = endpoint
- proc_env.update(env_vars)
proc = subprocess.Popen(
[bootstrap_path],
diff --git a/tests/test_lambda.py b/tests/test_lambda.py
index e6462e9a..807646a4 100644
--- a/tests/test_lambda.py
+++ b/tests/test_lambda.py
@@ -697,6 +697,64 @@ def test_lambda_python_env_vars_at_spawn(lam):
payload = json.loads(resp["Payload"].read())
assert payload["myVar"] == "from-spawn-py"
+def test_lambda_endpoint_url_not_overridden_by_function_env(lam):
+ """AWS_ENDPOINT_URL from function env vars must not override the
+ process-level value. When MiniStack runs in Docker, the host-mapped
+ port (e.g. 4568) is unreachable from inside the container — the
+ Lambda binary must always use MiniStack's internal endpoint.
+
+ This test verifies that the MiniStack server's AWS_ENDPOINT_URL takes
+ precedence over function-level env vars. It requires the server to
+ have AWS_ENDPOINT_URL set (as it does when running via docker-compose).
+ """
+ # Verify the MiniStack server has AWS_ENDPOINT_URL set by checking
+ # a baseline Lambda. If the server doesn't have it, the override
+ # logic has nothing to restore and this test is not meaningful.
+ probe_code = (
+ "import os\n"
+ "def handler(event, context):\n"
+ " return {'endpoint': os.environ.get('AWS_ENDPOINT_URL', '')}\n"
+ )
+ probe_name = f"lam-endpoint-probe-{_uuid_mod.uuid4().hex[:8]}"
+ lam.create_function(
+ FunctionName=probe_name,
+ Runtime="python3.11",
+ Role=_LAMBDA_ROLE,
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(probe_code)},
+ )
+ resp = lam.invoke(FunctionName=probe_name, Payload=b"{}")
+ server_endpoint = json.loads(resp["Payload"].read()).get("endpoint", "")
+ if not server_endpoint:
+ pytest.skip("MiniStack server does not have AWS_ENDPOINT_URL set "
+ "(run with docker-compose to test endpoint override)")
+
+ # Now test with a function that sets a conflicting AWS_ENDPOINT_URL.
+ code = (
+ "import os\n"
+ "def handler(event, context):\n"
+ " return {'endpoint': os.environ.get('AWS_ENDPOINT_URL', 'unset')}\n"
+ )
+ fname = f"lam-endpoint-override-{_uuid_mod.uuid4().hex[:8]}"
+ lam.create_function(
+ FunctionName=fname,
+ Runtime="python3.11",
+ Role=_LAMBDA_ROLE,
+ Handler="index.handler",
+ Code={"ZipFile": _make_zip(code)},
+ Environment={"Variables": {
+ "AWS_ENDPOINT_URL": "http://should-be-overridden:9999",
+ }},
+ )
+ resp = lam.invoke(FunctionName=fname, Payload=b"{}")
+ payload = json.loads(resp["Payload"].read())
+ # The Lambda must see the server's endpoint, not the function env var.
+ assert payload["endpoint"] != "http://should-be-overridden:9999", (
+ "Function-level AWS_ENDPOINT_URL must not override internal endpoint"
+ )
+ assert payload["endpoint"] == server_endpoint
+
+
def test_lambda_dynamodb_stream_esm(lam, ddb):
# Create table with streams enabled
ddb.create_table(