bug: mocked Throw responses lose the mocked Error and Cause for most service integrations

[anikolaiev]

bug: mocked Throw responses lose the mocked Error and Cause for most service integrations

Is there an existing report for this?

Searched the Bugs discussions and the archived issue tracker. The only related item is
localstack/localstack#11712, the feature request that added mock config support. This is a
separate defect in how mocked Throw responses are evaluated.

Current Behavior

With SFN_MOCK_CONFIG, a mocked response of the form

{"Throw": {"Error": "ApiGateway.422", "Cause": "Unable to create a school"}}

does not fail the task with ApiGateway.422. It fails with ApiGateway.FailureEventException
and an empty cause:

"taskFailedEventDetails":      {"error": "ApiGateway.FailureEventException", "cause": ""}
"executionFailedEventDetails": {"error": "ApiGateway.FailureEventException"}

Because the error name is not the one that was mocked, Catch and Retry blocks never match.
Any state machine whose error handling depends on the mocked error name is untestable — the
execution fails with an error nobody wrote, and the Catch target is never reached.

Mocked Return responses are unaffected; this is specific to Throw.

Expected Behavior

The task fails with the mocked error name and cause, so Catch and Retry match as they do
against real AWS.

How are you starting LocalStack?

docker run / docker compose, with SFN_MOCK_CONFIG pointing at a mounted mock config file.

Steps To Reproduce

State machine — catches the mocked error and routes to a Fail state:

{
  "StartAt": "Call API",
  "States": {
    "Call API": {
      "Type": "Task",
      "Resource": "arn:aws:states:::apigateway:invoke",
      "Parameters": {
        "ApiEndpoint": "example.execute-api.eu-west-1.amazonaws.com",
        "Method": "POST",
        "Stage": "v1",
        "Path": "/things"
      },
      "Catch": [{"ErrorEquals": ["ApiGateway.422"], "Next": "Unprocessable"}],
      "End": true
    },
    "Unprocessable": {
      "Type": "Fail",
      "Error": "422",
      "Cause": "Unable to create a school"
    }
  }
}

Mock config:

{
  "StateMachines": {"Test": {"TestCases": {"Case": {"Call API": "Throw422"}}}},
  "MockedResponses": {"Throw422": {"0": {"Throw": {"Error": "ApiGateway.422", "Cause": "boom"}}}}
}

Then:

awslocal stepfunctions start-execution --state-machine-arn "<arn>#Case" --input '{}'
awslocal stepfunctions get-execution-history --execution-arn "<execution-arn>"

Expected: Catch matches, execution fails with error: "422", cause: "Unable to create a school".
Actual: execution fails with error: "ApiGateway.FailureEventException", empty cause.

Environment

- OS: macOS 15 (arm64), Docker via OrbStack 29.4.0
- LocalStack: 2026.7.3 (localstack/localstack:latest)

Also reproduced on localstack/localstack:4.10.0, and present in moto on current master.

Cause

_eval_mocked_response_throw() correctly builds a FailureEvent carrying the mocked error name
and raises it wrapped in FailureEventException:

# .../state_task/mock_eval_utils.py
def _eval_mocked_response_throw(env, mocked_response) -> None:
    task_failed_event_details = TaskFailedEventDetails(
        error=mocked_response.error, cause=mocked_response.cause
    )
    error_name = CustomErrorName(mocked_response.error)
    failure_event = FailureEvent(env=env, error_name=error_name, ...)
    raise FailureEventException(failure_event=failure_event)

Each integration's _from_error() then translates the exception into a TaskFailed event. Only a
few unwrap FailureEventException first. StateTaskServiceApiGateway does not:

# .../state_task/service/state_task_service_api_gateway.py
def _from_error(self, env, ex) -> FailureEvent:
    if isinstance(ex, SfnGatewayException):
        error_name = f"ApiGateway.{ex.response.status_code}"
        cause = ex.response.text
    else:
        ex_name = ex.__class__.__name__       # -> "FailureEventException"
        error_name = f"ApiGateway.{ex_name}"  # -> "ApiGateway.FailureEventException"
        cause = str(ex)                       # -> "" (FailureEventException never calls super().__init__)
    ...

So the deliberately constructed FailureEvent is discarded and replaced by one named after the
Python exception class.

The SfnGatewayException branch is correct, but it cannot be reached from a mocked response.
That exception is raised only inside _eval_service_task(), from a real HTTP response:

if response.status_code != 200:
    raise SfnGatewayException(parameters=task_parameters, response=response)

and the two paths are mutually exclusive:

# .../state_task/service/state_task_service.py
if env.is_mocked_mode():
    mocked_response: MockedResponse = env.get_current_mocked_response()
    eval_mocked_response(env=env, mocked_response=mocked_response)   # raises FailureEventException
else:
    self._eval_service_task(...)                                     # raises SfnGatewayException

In mocked mode _eval_service_task() never runs, so the only exception that reaches
_from_error() is FailureEventException, and the else branch is the only one available to
handle it. Error translation on real invocations is unaffected — this is specific to the mocked
path reusing a translator written for the real one.

Affected integrations

These unwrap FailureEventException in _from_error(), so a mocked Throw fails the task with
the mocked error name, and Catch / Retry match as expected:

• StateTaskLambda (the direct arn:aws:lambda:... resource)
• StateTaskServiceSfn
• StateTaskServiceBatch
• StateTaskServiceGlue

These do not unwrap it, so a mocked Throw fails the task with <Service>.FailureEventException
and an empty cause instead of the mocked values:

• StateTaskServiceApiGateway
• StateTaskServiceAwsSdk
• StateTaskServiceLambda (lambda:invoke)
• StateTaskServiceSqs
• StateTaskServiceDynamoDB
• StateTaskServiceSns
• StateTaskServiceEvents
• StateTaskServiceHttp
• StateTaskActivity

Worth noting that the AWS documentation example for mocked service integrations uses Lambda's
direct resource, which is one of the four that work — so the feature appears healthy until
another integration is used.

Verified present in all three implementations:

Implementation	Version checked
localstack/pro/core/services/stepfunctions/...	2026.7.3
localstack-core/localstack/services/stepfunctions/...	4.10.0
moto/stepfunctions/parser/...	current master

Suggested fix

Unwrap the carried failure event in each affected _from_error(), exactly as StateTaskLambda
already does:

if isinstance(ex, FailureEventException):
    return ex.failure_event

Handling it once in the shared base class would cover every integration and stop the same gap
reappearing as new ones are added.

Applying that unwrap at runtime is enough to make the reproduction above behave correctly, so
the fix is confirmed against the reported symptom.

Anything else?

The practical impact is that error-path testing is unavailable for most integrations. In our
case a suite of ~700 Step Functions specs is built around Catch behaviour on
apigateway:invoke, and none of those assertions can pass while the mocked error name is
replaced.