cdk.aws_stepfunctions.StateMachine: timeout does not apply to .asl.json definition

[marten-wirelab]

Describe the issue

It seems that the timeout argument to new cdk.aws_stepfunctions.StateMachine is only applied when the definitionBody is a ChainDefinitionBody. The only reference I can find is here:

aws-cdk/packages/aws-cdk-lib/aws-stepfunctions/lib/state-machine.ts

Line 486 in ebfaf89

graph.timeout = props.timeout;

This behavior is unclear from the documentation:

aws-cdk/packages/aws-cdk-lib/aws-stepfunctions/lib/state-machine.ts

Line 127 in ebfaf89

* Maximum run time for this state machine

For users that provide a .asl.json definitionBody, this can cause unexpected behavior.

Links

https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_stepfunctions.StateMachine.html#timeout

[pahud]

Hi @marten-wirelab,

Thank you for reporting this inconsistency!

Issue at a glance:

┌─────────────────────────────────────────────────────────┐
│ 🔴 Reported State                                       │
│ timeout param ignored for .asl.json definitions        │
│ Only works with ChainDefinitionBody                     │
└─────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────┐
│ 🔍 Root Cause                                           │
│ FileDefinitionBody/StringDefinitionBody.bind()         │
│ methods don't process timeout parameter                 │
└─────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────┐
│ 🟢 Suggested Fix                                        │
│ Modify ASL JSON to inject TimeoutSeconds property      │
│ in bind() methods + add validation warnings             │
└─────────────────────────────────────────────────────────┘

Root Cause: The timeout is only applied in StateMachine.constructor when definitionBody instanceof ChainDefinitionBody. The FileDefinitionBody and StringDefinitionBody classes don't process the timeout parameter in their bind() methods.

We were able to reproduce this. A minimal CDK app with three state machines — all with timeout: Duration.hours(1) — confirms only ChainDefinitionBody gets the timeout applied:

// All three use timeout: Duration.hours(1)
const chain = new sfn.Pass(this, 'PassState');

// 1) ChainDefinitionBody — timeout IS applied
new sfn.StateMachine(this, 'ChainSM', {
  definitionBody: sfn.DefinitionBody.fromChainable(chain),
  timeout: Duration.hours(1),
});

// 2) FileDefinitionBody — timeout IGNORED
new sfn.StateMachine(this, 'FileSM', {
  definitionBody: sfn.DefinitionBody.fromFile('definition.asl.json'),
  timeout: Duration.hours(1),
});

// 3) StringDefinitionBody — timeout IGNORED
new sfn.StateMachine(this, 'StringSM', {
  definitionBody: sfn.DefinitionBody.fromString(JSON.stringify({
    StartAt: 'PassState',
    States: { PassState: { Type: 'Pass', End: true } },
  })),
  timeout: Duration.hours(1),
});

Synth output shows:

# ChainSM — timeout applied ✅
DefinitionString: '{"StartAt":"PassState","States":{"PassState":{"Type":"Pass","End":true}},"TimeoutSeconds":3600}'

# FileSM — no TimeoutSeconds anywhere ❌
DefinitionS3Location:
  Bucket: ...
  Key: ...

# StringSM — no TimeoutSeconds ❌
DefinitionString: '{"StartAt":"PassState","States":{"PassState":{"Type":"Pass","End":true}}}'

Workaround: Until this is fixed, you can add TimeoutSeconds directly in your ASL JSON definition:

{
  "Comment": "My state machine",
  "StartAt": "PassState",
  "TimeoutSeconds": 3600,
  "States": {
    "PassState": { "Type": "Pass", "End": true }
  }
}

This bypasses the CDK timeout prop entirely and sets the timeout at the ASL level, which CloudFormation will pick up correctly.

Suggested Solution: Modify the bind() methods in FileDefinitionBody and StringDefinitionBody to parse the ASL JSON and inject the TimeoutSeconds property when sfnProps.timeout is specified. This would ensure consistent behavior across all definition body types.

The implementation of the fix would involve:

1. Updating both definition body classes to handle timeout
2. Adding appropriate validation/warnings
3. Adding test cases for the new behavior