在AWS CDK TypeScript中为Step Function的Fargate任务配置Catch时遇部署错误

问题描述 #

部署状态机时出现以下错误：
无效的状态机定义：'MISSING_TRANSITION_TARGET: 缺少'Next'目标: $.Failed'

问题出在自定义任务状态的Catch配置中，错误使用JSON路径$.Failed引用跳转目标，同时未正确关联Failed状态到状态机定义。

错误原因 #

1. 目标引用方式错误：$.Failed是JSON路径语法，用于读取输入数据字段，而非状态机内的状态名称，Step Function无法识别该状态目标。
2. 状态未正确关联：虽创建了Failed状态，但未通过正确名称引用或确保其被包含在状态机定义范围内。

解决方案 #

步骤1：保存Failed状态的引用 #

将Failed状态赋值给变量，方便后续引用其名称：

const failedState = new sfn.CustomState(this, "Failed", {
  stateJson: {
    Type: "Fail",
  },
});

步骤2：修正Catch中的目标引用 #

将Catch配置里的Next值改为Failed状态的stateName（状态的实际名称）：

Catch: [
  {
    ErrorEquals: ["States.All"],
    Next: failedState.stateName, // 使用状态实例的stateName属性
    ResultPath: "$.error",
  },
],

步骤3：确保状态包含在状态机范围内 #

由于Failed状态在同一个CDK作用域（this）下创建，CDK会自动将其纳入状态机定义范围，无需额外链式调用（它是终止状态，无需后续跳转）。

完整修正后的代码示例 #

import * as sfn from "aws-cdk-lib/aws-stepfunctions";
import { Duration } from "aws-cdk-lib";

// 定义Failed终止状态
const failedState = new sfn.CustomState(this, "Failed", {
  stateJson: {
    Type: "Fail",
  },
});

// 自定义Fargate任务状态的JSON配置
const stateJson = {
  Type: 'Task',
  Resource: 'arn:aws:states:::ecs:runTask.sync',
  Retry: [
    {
      ErrorEquals: ["ECS.AmazonECSException"],
      IntervalSeconds: 2,
      MaxAttempts: 6,
      BackoffRate: 2,
    }
  ],
  Catch: [
    {
      ErrorEquals: ["States.All"],
      Next: failedState.stateName, // 正确引用Failed状态的名称
      ResultPath: "$.error",
    },
  ],
  Parameters: {
    LaunchType: "FARGATE",
    Cluster: clusterName,
    TaskDefinition: TaskDefinition,
  },
  ResultPath: '$.FargateOutput',
};

// 创建自定义任务状态
const customTask = new sfn.CustomState(this, 'my custom task', {
  stateJson,
});

// 构建状态机流程链：任务成功后进入finalStatus，失败后通过Catch跳转至failedState
const chain = sfn.Chain.start(customTask)
  .next(finalStatus);

// 创建状态机
const stateMachine = new sfn.StateMachine(this, 'StateMachine', {
  definition: chain,
  timeout: Duration.seconds(30),
});

关键说明 #

• 状态机中跳转目标必须使用状态的名称字符串，而非JSON路径。
• 所有需要被状态机识别的状态，需在同一个CDK作用域下创建，CDK会自动处理状态的注册和关联。

内容的提问来源于stack exchange，提问作者Sanyukta Agrawal