bug: Step Functions States.Format with escaped curly braces causes KeyError

[christian-hawk]

Is there an existing issue for this?

• [X] I have searched the existing issues

Current Behavior

When using States.Format intrinsic function with escaped curly braces (\{ and \}) to produce literal JSON output, LocalStack throws a KeyError instead of correctly interpreting the escaped braces as literal characters.

The execution fails with:

{
    "status": "FAILED",
    "error": "States.Runtime",
    "cause": "KeyError('\"key\"')"
}

Expected Behavior

According to AWS documentation, escaped curly braces (\{ and \}) should be treated as literal characters in the output string, not as placeholders or variable references.

The execution should succeed and produce: {"result": "{\"key\":\"test123\"}"}

How are you starting LocalStack?

With a docker-compose file

Steps To Reproduce

How are you starting localstack (e.g., bin/localstack command, arguments, or docker-compose.yml)

services:
  localstack:
    image: localstack/localstack-pro
    ports:
      - "4566:4566"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN}

Client commands (e.g., AWS SDK code snippet, or sequence of "awslocal" commands)

1. Create a simple state machine with States.Format using escaped braces:

{
    "Comment": "Test States.Format with escaped braces",
    "StartAt": "TestFormat",
    "States": {
        "TestFormat": {
            "Type": "Pass",
            "Parameters": {
                "result.$": "States.Format('\\{\"key\":\"{}\"\\}', $.value)"
            },
            "End": true
        }
    }
}

2. Deploy to LocalStack:

awslocal stepfunctions create-state-machine \
  --name "test-format-escape" \
  --definition file://test_sfn.json \
  --role-arn "arn:aws:iam::000000000000:role/step-functions-role"

3. Execute with input:

awslocal stepfunctions start-execution \
  --state-machine-arn "arn:aws:states:us-east-1:000000000000:stateMachine:test-format-escape" \
  --input '{"value": "test123"}'

4. Check execution result:

awslocal stepfunctions describe-execution --execution-arn <execution-arn>

Result shows KeyError('\"key\"') instead of successful execution.

Environment

• OS: Linux (Docker)
• LocalStack: LocalStack version: 4.10.1.dev17 LocalStack Docker image sha: localstack/localstack-pro LocalStack build date: 2025-11-10 LocalStack build git hash: 061cd3109

Anything else?

From LocalStack logs, the error trace shows:

Exception=KeyError, Details=['"key"'] at '(StringFormat| {'name': (StatesFunctionName| {'name': 'orma', 'function_type': <StatesFunctionNameType.Format: 12>}, 'argument_list': (ArgumentList| {'arguments': [(ArgumentLiteral| {'definition_value': '\\\\{"key":"{}"\\\\}'}, ...

The definition_value shows \\\\{ (4 backslashes) instead of the expected \\{ (2 backslashes), suggesting double-escaping is occurring during intrinsic function processing.

Related: PR #12222 mentions that escape sequences in intrinsic functions were not fully addressed.

[localstack-bot]

Welcome to LocalStack! Thanks for reporting your first issue and our team will be working towards fixing the issue for you or reach out for more background information. We recommend joining our Slack Community for real-time help and drop a message to LocalStack Support if you are a licensed user! If you are willing to contribute towards fixing this issue, please have a look at our contributing guidelines.