Step Functions: CloudFormation DefinitionS3Location with a YAML definition fails at CreateStateMachine (ASLParserException) — real AWS converts YAML→JSON, LocalStack does not

[gj-honey]

Is there an existing issue / discussion for this?

I searched the Bugs category and the archived localstack/localstack tracker.
Closest prior art, none matching this path:

• bug: StateMachine yaml Definition is not supported (DefinitionString works) localstack#5204 — inline CFN Definition in YAML unsupported, inline
  JSON DefinitionString works. Reportedly fixed, but not for DefinitionS3Location.
• bug: Step Functions CloudFormation "update" handler doesn't support "DefinitionS3Location" field localstack#11255 — DefinitionS3Location not handled in the CFN update handler.
• Discussion Step Function Definition File is Returning Invalid When Using Jsonata But Is Valid #18 — a different Step Functions issue (JSONata Arguments via the
  validate API on a JSON definition), already fixed.

Current behaviour

Deploying an AWS::StepFunctions::StateMachine whose definition is supplied via
DefinitionS3Location pointing at a YAML ASL file fails at create time:

Resource provider operation failed ... CreateStateMachine ...
InvalidDefinition: ASLParserException line 1:7, at :, mismatched input ':' expecting '{'

line 1:7 is the : after the top-level Comment: key — the raw YAML is being
handed to LocalStack's JSON-only ASL parser, i.e. the YAML→JSON conversion that
real CloudFormation performs for an S3-located definition isn't happening.

Expected behaviour

Real CloudFormation accepts a JSON or YAML file at DefinitionS3Location and
converts it before calling Step Functions, so the same template deploys on AWS.
LocalStack should perform the same YAML→JSON handling. (An inline JSON
DefinitionString already works.)

How are you starting LocalStack?

localstack start -d (CLI)

Steps to reproduce

1. Author a state machine definition as YAML (statemachine.asl.yaml), e.g. with a
   top-level Comment: key.
2. In CDK: new sfn.StateMachine(this, 'SM', { definitionBody: sfn.DefinitionBody.fromFile('statemachine.asl.yaml'), }) — fromFile emits DefinitionS3Location.
3. cdklocal bootstrap && cdklocal deploy.

→ Stack rolls back; the state machine is CREATE_FAILED with the
ASLParserException above.

Workaround: convert YAML→JSON at synth and pass it inline as a
DefinitionString — DefinitionBody.fromString(JSON.stringify(parse(readFileSync(...)))).
This deploys and executes correctly (verified: CREATE_COMPLETE, and an execution
succeeds with DefinitionSubstitutions resolving normally).

Environment

• LocalStack CLI: 2026.5.3
• LocalStack image: localstack/localstack-pro:dev — 2026.6.0.dev249 (build 2026-06-12, git 73bfaeb5e)
• aws-cdk-lib 2.257.x via cdklocal (aws-cdk-local 3.0.4)
• Host: macOS (Apple Silicon), Docker Desktop

Anything else?

AWS reference: the DefinitionS3Location docs state the file "must be a JSON or
YAML file." Same root-cause class as #5204, just on the S3-located path rather than
the inline Definition property.

nb: This was authored via Claude