Skip to content

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

fix(lambda): report Sandbox.Timedout when a function times out (#1992)

mishukdutta-cz2022b04237a2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a91c58b..dbaa58a2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -68,6 +68,10 @@ Versioning follows [Semantic Versioning](https://semver.org/).
- **CloudFormation — `Fn::Select` in a condition** — a condition such as `!Not [!Equals [!Select [2, !Ref KeySpec], ""]]` was always true; conditions now resolve `Fn::Select`, and an index outside the list fails with `Template error: Fn::Select cannot select nonexistent value at index N`, in conditions and in properties. Contributed by @mishukdutta-cz.
- **CloudFormation — `Ref` to a list parameter** — a `Ref` to a `CommaDelimitedList` or `List<...>` parameter gave the raw string, so a list property got one item per character; it now gives the space-trimmed list. A list in a nested stack's `Parameters` or in an `AWS::SSM::Parameter` `Value` fails the resource. Contributed by @mishukdutta-cz.
+### Fixed
+
+- **Lambda — a timed-out invocation reports `Sandbox.Timedout`** — a function that ran past its `Timeout` returned `errorType` `Runtime.ExitError`, so a Step Functions `Retry` or `Catch` on `Sandbox.Timedout` never matched, and the execution failed where it recovers on AWS. All executors now return `Sandbox.Timedout` with the message `Task timed out after N.00 seconds`, as the Lambda and Step Functions error-handling docs describe. A runtime that exits before it responds still reports `Runtime.ExitError`.
+
## [1.5.20] — 2026-10-01
### Added
diff --git a/ministack/core/lambda_runtime.py b/ministack/core/lambda_runtime.py
index cefe8fe1..cb2153f5 100644
--- a/ministack/core/lambda_runtime.py
+++ b/ministack/core/lambda_runtime.py
@@ -2130,6 +2130,7 @@ class ProvidedWorker(Worker):
deadline = time.monotonic() + timeout
failure = None
+ failure_type = "Runtime.ExitError"
while not self._response_ready.wait(
min(_PROVIDED_POLL, max(0.0, deadline - time.monotonic()))):
proc = self._proc
@@ -2142,6 +2143,7 @@ class ProvidedWorker(Worker):
break
if time.monotonic() >= deadline:
failure = f"Task timed out after {timeout}.00 seconds"
+ failure_type = "Sandbox.Timedout"
break
if failure is not None:
logger.warning("Lambda %s: %s", self.func_name, failure)
@@ -2149,7 +2151,7 @@ class ProvidedWorker(Worker):
return {
"status": "error",
"error": failure,
- "error_payload": {"errorMessage": failure, "errorType": "Runtime.ExitError"},
+ "error_payload": {"errorMessage": failure, "errorType": failure_type},
"cold_start": cold,
"log": self._drain_stderr(),
}
diff --git a/ministack/services/lambda_svc.py b/ministack/services/lambda_svc.py
index b1a56523..d876f35c 100644
--- a/ministack/services/lambda_svc.py
+++ b/ministack/services/lambda_svc.py
@@ -3958,7 +3958,7 @@ def _rie_terminal_result(exc: BaseException, timeout: int, logs: str) -> dict:
# agrees on one shape.
body = {
"errorMessage": f"Task timed out after {timeout}.00 seconds",
- "errorType": "Runtime.ExitError",
+ "errorType": "Sandbox.Timedout",
}
return {
"body": body, "error": True, "function_error": "Unhandled",
@@ -4027,7 +4027,7 @@ def _invoke_rie(container, event: dict, timeout: int) -> dict:
result["function_error"] = function_error
if isinstance(parsed, str) and _RIE_TIMEOUT_TEXT_RE.fullmatch(parsed):
# A bare timeout string: same shape as _rie_terminal_result.
- result["body"] = {"errorMessage": parsed, "errorType": "Runtime.ExitError"}
+ result["body"] = {"errorMessage": parsed, "errorType": "Sandbox.Timedout"}
result["timeout"] = True
return result
except (urllib.error.URLError, ConnectionRefusedError, OSError) as exc:
@@ -4805,7 +4805,7 @@ def _execute_function_docker(func: dict, event: dict) -> dict:
msg = str(exc).lower()
if "timed out" in msg or "read timed out" in msg:
err_body = {"errorMessage": f"Task timed out after {timeout}.00 seconds",
- "errorType": "Runtime.ExitError"}
+ "errorType": "Sandbox.Timedout"}
else:
err_body = {"errorMessage": str(exc), "errorType": type(exc).__name__}
logger.error("Lambda %s invocation error: %s", fn_name, exc)
@@ -5279,7 +5279,7 @@ def _execute_function_warm(func: dict, event: dict) -> dict:
error_msg = result.get("error", "Unknown error")
error_type = "Runtime.HandlerError"
if "timed out" in error_msg.lower():
- error_type = "Runtime.ExitError"
+ error_type = "Sandbox.Timedout"
return {
"body": {
"errorMessage": error_msg,
@@ -5370,7 +5370,7 @@ def _execute_function_provided_warm(func: dict, event: dict,
if isinstance(payload, dict):
return {"body": payload, "error": True, "log": result.get("log", "")}
error_msg = result.get("error", "Unknown error")
- error_type = ("Runtime.ExitError" if "timed out" in error_msg.lower()
+ error_type = ("Sandbox.Timedout" if "timed out" in error_msg.lower()
else "Runtime.HandlerError")
return {
"body": {"errorMessage": error_msg, "errorType": error_type},
@@ -5548,7 +5548,7 @@ def _execute_function_provided(func: dict, event: dict) -> dict:
proc.kill()
stdout, stderr = proc.communicate(timeout=5)
logs = (stdout.decode("utf-8", errors="replace") + stderr.decode("utf-8", errors="replace")).strip()
- return {"body": {"errorMessage": f"Lambda timed out after {timeout}s: {logs[:500]}", "errorType": "Runtime.ExitError"}, "error": True}
+ return {"body": {"errorMessage": f"Task timed out after {timeout}.00 seconds", "errorType": "Sandbox.Timedout"}, "error": True, "log": logs}
finally:
server.shutdown()
@@ -5730,7 +5730,7 @@ def _execute_function_local(func: dict, event: dict) -> dict:
return {
"body": {
"errorMessage": f"Task timed out after {timeout}.00 seconds",
- "errorType": "Runtime.ExitError",
+ "errorType": "Sandbox.Timedout",
},
"error": True,
"log": _log,
diff --git a/tests/test_lambda.py b/tests/test_lambda.py
index 81e1a7c4..59c0fe5d 100644
--- a/tests/test_lambda.py
+++ b/tests/test_lambda.py
@@ -10722,7 +10722,7 @@ def test_invoke_rie_does_not_re_run_a_handler_that_timed_out():
# The message and type the local and catch-all docker paths already emit.
assert result["body"] == {
"errorMessage": "Task timed out after 3.00 seconds",
- "errorType": "Runtime.ExitError",
+ "errorType": "Sandbox.Timedout",
}
# Internal signal to _execute_function_docker: do not pool this container.
assert result["timeout"] is True
@@ -10822,7 +10822,7 @@ def test_lambda_docker_timeout_recycles_the_container(monkeypatch):
for result in (first, second):
assert result["error"] is True
- assert result["body"]["errorType"] == "Runtime.ExitError"
+ assert result["body"]["errorType"] == "Sandbox.Timedout"
assert result["body"]["errorMessage"] == "Task timed out after 3.00 seconds"
# The recycle signal is internal and must not reach the caller.
assert "timeout" not in result
@@ -10997,7 +10997,7 @@ def test_lambda_docker_timeout_returns_task_timed_out_promptly(lam):
elapsed = time.time() - started
assert resp.get("FunctionError") == "Unhandled"
assert payload["errorMessage"] == "Task timed out after 3.00 seconds"
- assert payload["errorType"] == "Runtime.ExitError"
+ assert payload["errorType"] == "Sandbox.Timedout"
# One timeout, not a retry storm (broken code took 4x+ the Timeout and
# surfaced a raw "Lambda RIE failed" instead).
assert elapsed < 9, f"timeout took {elapsed:.1f}s — retry storm?"
@@ -14234,7 +14234,7 @@ def test_invoke_rie_reports_a_bare_string_timeout_as_a_function_error():
assert result["function_error"] == "Unhandled"
assert result["body"] == {
"errorMessage": "Task timed out after 300.00 seconds",
- "errorType": "Runtime.ExitError",
+ "errorType": "Sandbox.Timedout",
}
assert result["timeout"] is True