Skip to content

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

fix(sfn): handle escape sequences in States.Format template strings (#315)

Jay Janssenf583c95b123d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4f9a697b..bb4981fe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,13 @@ Versioning follows [Semantic Versioning](https://semver.org/).
---
+## [Unreleased]
+
+### Fixed
+- **SFN States.Format escape handling** — `States.Format` now correctly processes `\'`, `\{`, `\}`, and `\` escape sequences in template strings, matching AWS behavior. Escaped quotes no longer truncate the template during intrinsic argument parsing. Interpolated values are preserved verbatim (backslashes in arguments are not interpreted as escapes).
+
+---
+
## [1.2.12] — 2026-04-14
### Added
diff --git a/ministack/services/stepfunctions.py b/ministack/services/stepfunctions.py
index 9710f2dc..0d9ec31a 100644
--- a/ministack/services/stepfunctions.py
+++ b/ministack/services/stepfunctions.py
@@ -1758,7 +1758,15 @@ def _parse_intrinsic_args(s, pos):
arg, pos = _parse_intrinsic_call(s, pos)
args.append(arg)
elif ch == "'":
- end = s.index("'", pos + 1)
+ # Scan for closing quote, handling \' escapes.
+ end = pos + 1
+ while end < len(s):
+ if s[end] == '\\' and end + 1 < len(s):
+ end += 2
+ elif s[end] == "'":
+ break
+ else:
+ end += 1
args.append(("str", s[pos + 1 : end]))
pos = end + 1
elif ch == "$":
@@ -1845,15 +1853,27 @@ def _exec_intrinsic(node, data, ctx):
merged.update(args[1])
return merged
elif name == "States.Format":
+ # AWS States.Format: \' → ', \{ → {, \} → }, \\ → \ in
+ # template segments only. Interpolated values are verbatim.
template = args[0]
- parts = template.split("{}")
- result_parts = []
- for i, part in enumerate(parts):
- result_parts.append(part)
- if i < len(parts) - 1 and i < len(args) - 1:
- val = args[i + 1]
- result_parts.append(str(val) if not isinstance(val, str) else val)
- return "".join(result_parts)
+ arg_idx = 1
+ out: list[str] = []
+ i = 0
+ while i < len(template):
+ ch = template[i]
+ if ch == '\\' and i + 1 < len(template):
+ out.append(template[i + 1])
+ i += 2
+ elif ch == '{' and i + 1 < len(template) and template[i + 1] == '}':
+ if arg_idx < len(args):
+ val = args[arg_idx]
+ out.append(str(val) if not isinstance(val, str) else val)
+ arg_idx += 1
+ i += 2
+ else:
+ out.append(ch)
+ i += 1
+ return "".join(out)
elif name == "States.ArrayGetItem":
return args[0][int(args[1])]
elif name == "States.Array":
diff --git a/tests/test_sfn.py b/tests/test_sfn.py
index f30f431a..7c94ca78 100644
--- a/tests/test_sfn.py
+++ b/tests/test_sfn.py
@@ -334,6 +334,39 @@ def test_sfn_intrinsic_format(sfn, sfn_sync):
output = json.loads(resp["output"])
assert output["greeting"] == "Hello Jay from SF"
+def test_sfn_intrinsic_format_escapes(sfn, sfn_sync):
+ """States.Format handles \\' \\{ \\} \\\\ escapes in template only."""
+ definition = json.dumps({
+ "StartAt": "Fmt",
+ "States": {
+ "Fmt": {
+ "Type": "Pass",
+ "Parameters": {
+ "quoted.$": "States.Format('it\\'s {}', $.x)",
+ "braces.$": "States.Format('\\{literal\\}')",
+ "backslash.$": "States.Format('C:\\\\tmp')",
+ "preserved.$": "States.Format('path: {}', $.path)",
+ },
+ "End": True,
+ }
+ },
+ })
+ sm = sfn.create_state_machine(
+ name="sfn-intrinsic-fmt-esc",
+ definition=definition,
+ roleArn="arn:aws:iam::000000000000:role/R",
+ )
+ resp = sfn_sync.start_sync_execution(
+ stateMachineArn=sm["stateMachineArn"],
+ input=json.dumps({"x": "fine", "path": "C:\\tmp\\file"}),
+ )
+ assert resp["status"] == "SUCCEEDED"
+ output = json.loads(resp["output"])
+ assert output["quoted"] == "it's fine"
+ assert output["braces"] == "{literal}"
+ assert output["backslash"] == "C:\\tmp"
+ assert output["preserved"] == "path: C:\\tmp\\file"
+
def test_sfn_intrinsic_nested(sfn, sfn_sync):
"""Nested intrinsic: States.StringToJson(States.Format(...))"""
definition = json.dumps({