Skip to content

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

@christian-hawk

Description

@christian-hawk

Is there an existing issue for this?

  • 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
        }
    }
}
  1. 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"
  1. Execute with input:
awslocal stepfunctions start-execution \
  --state-machine-arn "arn:aws:states:us-east-1:000000000000:stateMachine:test-format-escape" \
  --input '{"value": "test123"}'
  1. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions