AWS step-functions documentation change
Summary
Updated error handling documentation with clarifications on error types, catcher usage, Lambda exception handling best practices, and example improvements.
Security assessment
The changes focus on error handling mechanics, retry/catch configurations, and reliability best practices. While they emphasize handling Lambda service exceptions (Lambda.ServiceException/Lambda.SdkClientException), this relates to fault tolerance rather than addressing a specific security vulnerability. No concrete evidence of security vulnerability mitigation is present.
Diff
diff --git a/step-functions/latest/dg/concepts-error-handling.md b/step-functions/latest/dg/concepts-error-handling.md index 9584ace72..c5c639648 100644 --- a//step-functions/latest/dg/concepts-error-handling.md +++ b//step-functions/latest/dg/concepts-error-handling.md @@ -5 +5 @@ -Error namesRetrying after an errorFallback statesState machine examples using Retry and using Catch +Error namesRetrying after an errorFallback statesExamples using Retry and Catch @@ -20 +20 @@ All states, except `Pass` and `Wait` states, can encounter runtime errors. Error -When a state reports an error, AWS Step Functions defaults to failing the **entire** state machine execution. Step Functions also has more advanced error handling features. You can set up your state machine to catch errors, retry failed states, and gracefully implement error handling protocols. +When a state reports an error, Step Functions defaults to failing the **entire** state machine execution. Step Functions also has more advanced error handling features. You can set up your state machine to catch errors, retry failed states, and gracefully implement error handling protocols. @@ -22 +22 @@ When a state reports an error, AWS Step Functions defaults to failing the **enti -###### Tip +Step Functions catchers are available for **Task** , **Parallel** and **Map** states, but not for top-level state machine execution failures. To handle executions you anticipate might fail, your caller can handle the error, or you might nest those executions inside child workflows to catch errors inside your parent workflow. Alternatively, you might choose to listen for `TIMED_OUT` events from Standard workflows with an EventBridge bus and invoke an action to handle the failed execution. @@ -24 +24,3 @@ When a state reports an error, AWS Step Functions defaults to failing the **enti -To deploy an example of a workflow that includes error handling, see [Error Handling](https://catalog.workshops.aws/stepfunctions/handling-errors) in _The AWS Step Functions Workshop_. +###### Practical examples for handling errors + +To deploy an example of a workflow that includes error handling, see [Handling error conditions in a Step Functions state machine](./tutorial-handling-error-conditions.html) tutorial in this guide, and [Error Handling](https://catalog.workshops.aws/stepfunctions/handling-errors) in _The AWS Step Functions Workshop_. @@ -28 +30,5 @@ To deploy an example of a workflow that includes error handling, see [Error Hand -Step Functions identifies errors in the Amazon States Language using case-sensitive strings, known as _error names_. The Amazon States Language defines a set of built-in strings that name well-known errors, all beginning with the `States.` prefix. +Step Functions identifies errors using case-sensitive strings, known as _error names_. The Amazon States Language defines a set of built-in strings that name well-known errors, all beginning with the `States.` prefix. + +States can report errors with other names. However, the error names cannot begin with the `States.` prefix. + +Ensure your production code can handle AWS Lambda service exceptions (`Lambda.ServiceException` and `Lambda.SdkClientException`). For more information, see how to [Handle transient Lambda service exceptions](./sfn-best-practices.html#bp-lambda-serviceexception) in _Best practices_. @@ -35,3 +41 @@ A wildcard that matches any known error name. -###### Note - -The States.ALL error type must appear alone in a Catcher and cannot catch the `States.DataLimitExceeded` terminal error or `Runtime` error types. +The `States.ALL` error type must appear alone in a `Catcher` and cannot catch the `States.DataLimitExceeded` terminal error or `Runtime` error types. @@ -45,0 +50,2 @@ States.DataLimitExceeded` ** +A terminal error which cannot be caught by the `States.ALL` error type. + @@ -48 +54 @@ Reported due to the following conditions: - * When the output of a connector is larger than payload size quota. + * Output of a connector is larger than payload size quota. @@ -50 +56 @@ Reported due to the following conditions: - * When the output of a state is larger than payload size quota. + * Output of a state is larger than payload size quota. @@ -52 +58 @@ Reported due to the following conditions: - * When, after `Parameters` processing, the input of a state is larger than the payload size quota. + * After `Parameters` processing, the input of a state is larger than the payload size quota. @@ -59,4 +64,0 @@ For more information on quotas, see [Step Functions service quotas](./service-qu -###### Note - -`DataLimitExceeded` is a terminal error which cannot be caught by the `States.ALL` error type. - @@ -75,3 +77 @@ A `Task` state failed to send a heartbeat for a period longer than the `Heartbea -###### Note - -HeartbeatTimeout is only available inside the `Catch` and `Retry` fields. +`HeartbeatTimeout` is available inside the `Catch` and `Retry` fields. @@ -120,3 +120 @@ A `Task` state failed during the execution. When used in a retry or catch, `Stat -A `Task` state either ran longer than the `TimeoutSeconds` value, or failed to send a heartbeat for a period longer than the `HeartbeatSeconds` value. - -Additionally, if a state machine runs longer than the specified `TimeoutSeconds` value, the execution fails with a `States.Timeout` error. +Reported when a `Task` state runs longer than the `TimeoutSeconds` value or failed to send a heartbeat for a period longer than the `HeartbeatSeconds` value. @@ -124 +122 @@ Additionally, if a state machine runs longer than the specified `TimeoutSeconds` -States can report errors with other names. However, these error names can't begin with the `States.` prefix. +If a _nested state machine_ throws a `States.Timeout`, the parent will receive a `States.TaskedFailed` error. @@ -126 +124 @@ States can report errors with other names. However, these error names can't begi -As a best practice, ensure production code can handle AWS Lambda service exceptions (`Lambda.ServiceException` and `Lambda.SdkClientException`). For more information, see [Handle transient Lambda service exceptions](./sfn-best-practices.html#bp-lambda-serviceexception). +A `States.Timeout` error is also reported when an entire state machine execution runs longer than the specified `TimeoutSeconds` value. @@ -148,4 +145,0 @@ A retrier contains the following fields: -###### Note - -Retries are treated as state transitions. For information about how state transitions affect billing, see [Step Functions Pricing](https://aws.amazon.com/step-functions/pricing/). - @@ -187,0 +182,4 @@ For example, say you have set `MaxAttempts` as 3, `IntervalSeconds` as 2, and `B +###### Note + +Retries are treated as state transitions. For information about how state transitions affect billing, see [Step Functions Pricing](https://aws.amazon.com/step-functions/pricing/). + @@ -306 +304 @@ A string that must exactly match one of the state machine's state names. -**`ResultPath` (Optional)** +**`ResultPath` (JSONPath, Optional)** @@ -327 +325 @@ The following example of a `Catch` field transitions to the state named `Recover -###### Note +###### How many errors can a catcher catch? @@ -329 +327 @@ The following example of a `Catch` field transitions to the state named `Recover -Each catcher can specify multiple errors to handle. +Each catcher can specify **multiple errors** to handle. @@ -335 +333 @@ When Step Functions transitions to the state specified in a catch name, the obje -In this example, the first catcher contains a `ResultPath` field. This works similarly to a `ResultPath` field in a state's top level, resulting in two possibilities: +In the previous JSONPath example, the first catcher contains a `ResultPath` field. This works similarly to a `ResultPath` field in a state's top level, resulting in two possibilities: @@ -337 +335 @@ In this example, the first catcher contains a `ResultPath` field. This works sim - * It takes the results of that state's execution and overwrites either all of, or a portion of, the state's input. + * Take the results of that state's execution and overwrite either all of, or a portion of, the state's input. @@ -339 +337 @@ In this example, the first catcher contains a `ResultPath` field. This works sim - * It takes the results and adds them to the input. In the case of an error handled by a catcher, the result of the state's execution is the error output. + * Take the results and adds them to the input. In the case of an error handled by a catcher, the result of the state's execution is the error output. @@ -346,3 +344 @@ Thus, for the first catcher in the example, the catcher adds the error output to -###### Note - -If you don't specify the `ResultPath` field, it defaults to `$`, which selects and overwrites the entire input. +For JSONPath workflows, if you don't specify the `ResultPath` field, it defaults to `$`, which selects and overwrites the entire input. @@ -365 +361 @@ A catcher returns a string payload as an output. When working with service integ -## State machine examples using Retry and using Catch +## State machine examples using Retry and Catch @@ -378,4 +373,0 @@ This is a definition of a Node.js Lambda function that sleeps for 10 seconds. In -###### Note - -When you create this Lambda function in the Lambda console, remember to change the **Timeout** value in the **Advanced settings** section from 3 seconds (default) to 11 seconds. - @@ -387,0 +380,4 @@ When you create this Lambda function in the Lambda console, remember to change t +###### Timeout settings for the function + +When you create the Lambda function for the examples, remember to set the `Timeout` value in the advanced settings to 11 seconds. + @@ -394 +390 @@ This state machine uses a `Retry` field to retry a function that fails and outpu - "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", + "Comment": "A Hello World example invoking Lambda function", @@ -415 +411 @@ This variant uses the predefined error code `States.TaskFailed`, which matches a - "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", + "Comment": "Hello World example which invokes a AWS Lambda function", @@ -432 +428 @@ This variant uses the predefined error code `States.TaskFailed`, which matches a -###### Note +###### Best practices for handling Lambda exceptions @@ -434 +430 @@ This variant uses the predefined error code `States.TaskFailed`, which matches a -As a best practice, tasks that reference a Lambda function should handle Lambda service exceptions. For more information, see [Handle transient Lambda service exceptions](./sfn-best-practices.html#bp-lambda-serviceexception). +Tasks that reference a Lambda function should handle Lambda service exceptions. For more information, see [Handle transient Lambda service exceptions](./sfn-best-practices.html#bp-lambda-serviceexception) in Best Practices. @@ -442 +438 @@ This example uses a `Catch` field. When a Lambda function outputs an error, it c - "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", + "Comment": "Hello World example which invokes a AWS Lambda function", @@ -466 +462 @@ This variant uses the predefined error code `States.TaskFailed`, which matches a - "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", + "Comment": "Hello World example which invokes a AWS Lambda function", @@ -492 +488 @@ This state machine uses a `Retry` field to retry a `Task` state that times out, - "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", + "Comment": "Hello World example which invokes a AWS Lambda function", @@ -516 +512 @@ This example uses a `Catch` field. When a timeout occurs, the state machine tran - "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda function", + "Comment": "Hello World example which invokes a AWS Lambda function", @@ -537 +533 @@ This example uses a `Catch` field. When a timeout occurs, the state machine tran -###### Note +###### Preserving state input and error in JSONPath @@ -539 +535 @@ This example uses a `Catch` field. When a timeout occurs, the state machine tran -You can preserve the state input and the error by using `ResultPath`. See [Use ResultPath to include both error and input in a Catch](./input-output-resultpath.html#input-output-resultpath-catch). +In JSONPath, you can preserve the state input and the error by using `ResultPath`. See [Use ResultPath to include both error and input in a Catch](./input-output-resultpath.html#input-output-resultpath-catch).