bug: Inline Map turns a nested States.TaskFailed into an invalid custom error name

[AndreKurait]

Additional version check — 2026-10-08

Still reproduced: the same nested task failure becomes States.Runtime with the invalid-custom-error-name diagnostic.

The comparison used an unmodified localstack/localstack-pro:2026.8.1 Linux ARM64 image,
repository digest sha256:4aef81c531684570d7b3cfd2805afa02194c929d52bbeedabb7d4874798b1572.
Vendor packages were localstack-core 2026.8.1, moto-ext 5.1.48, and bundled
boto3/botocore 1.43.78. HTTP probes used a separate boto3/botocore 1.43.101
client; the process-local security-group probe used the bundled interpreter.
The same scripts were used, with no custom extensions or provider source changes.
Owned test containers and the disposable network were removed.
This is a second specifically tested version, not a claim to have tested the latest release.

---

Existing report search

I searched the LocalStack issue tracker and current organization Discussions for this operation and failure. I did not find an existing report for this exact reproduction.

Current behavior

A child Standard workflow deliberately fails with the custom error ReproFailure. A parent inline Map invokes it through arn:aws:states:::states:startExecution.sync:2 and catches States.TaskFailed.

Instead of reaching that catch, execution fails with States.Runtime and the diagnostic:

Custom Error Names MUST NOT begin with the prefix 'States.', got 'States.TaskFailed'.

The workflow did not define a custom error named States.TaskFailed; that error is generated by the nested service integration.

This was reproduced through public APIs on a fresh, unmodified LocalStack container.

Expected behavior

The built-in task failure should propagate through the Map and reach its States.TaskFailed catch, retaining the child's ReproFailure cause. The parent should then finish successfully through its Caught state. The reserved-prefix restriction should continue to apply to actual custom error names.

Reference: Step Functions error handling.

Related but distinct: closed issue #10489 concerns definition-time handling of States.DataLimitExceeded. This reproduction creates the definition successfully and fails at runtime while propagating an inline Map iteration's built-in error.

Environment

• Tested on 2026-10-07, Linux, using localstack/localstack-pro:2026.7.5.
• Repository digest: sha256:0d74e1d2d7ce13a3cb25fc64cf15eb225f1c95c762e56e057bc6a9ed0ed29306.
• Vendor-installed distributions: localstack-core 2026.7.5, moto-ext 5.1.46, moto.__version__ = 5.1.21.dev, boto3/botocore 1.43.51.
• Fresh disposable container, no application code, no custom extensions, no source patches.
• This is an affected-version report, not a claim that the latest LocalStack release or standalone Moto still has the defect.

Fresh confirmation on 2026-10-08: the same discrepancy reproduced on Linux ARM64 against the same unmodified image, using a separate boto3/botocore 1.43.101 client. The disposable container and network were removed after the run. The startup block below includes the run's disabled DNS listener/default EC2-image downloads and temporary state storage; no provider source or extension was changed.

Steps to reproduce

Start a disposable instance on a free loopback port:

# LOCALSTACK_AUTH_TOKEN is read from your environment, never embedded in this report.
set -eu
container=$(docker run --rm -d \
  -p 127.0.0.1:4567:4566 -e LOCALSTACK_AUTH_TOKEN \
  -e DNS_ADDRESS=0 -e EC2_DOWNLOAD_DEFAULT_IMAGES=0 \
  --tmpfs /var/lib/localstack \
  localstack/localstack-pro:2026.7.5)
trap 'docker stop "$container" >/dev/null' EXIT
ready=false
for attempt in $(seq 1 60); do
  if curl --fail --silent http://127.0.0.1:4567/_localstack/health >/dev/null; then
    ready=true
    break
  fi
  sleep 1
done
"$ready"
python stepfunctions_map_task_failure.py --endpoint-url http://127.0.0.1:4567

Run the block in a disposable shell. Port 4567 must be free. The client needs boto3; it uses only dummy credentials and a loopback endpoint. It creates disposable resources and cleans them up in finally; the shell trap removes the container even when the script reports failure. A nonzero exit is expected while the reported discrepancy is present. No Docker socket mount or application services are required.

Complete standalone reproducer: stepfunctions_map_task_failure.py

"""Check a built-in nested task failure inside an inline Map on a local endpoint."""
import argparse
import json
import time
import uuid
from urllib.parse import urlsplit

import boto3
from botocore.config import Config


def run(endpoint):
    if urlsplit(endpoint).hostname not in {"localhost", "127.0.0.1", "::1"}:
        raise ValueError("This reproducer accepts only a loopback endpoint")
    options = {
        "endpoint_url": endpoint, "region_name": "us-east-1",
        "aws_access_key_id": "test", "aws_secret_access_key": "test",
        "config": Config(proxies={}, retries={"max_attempts": 0}),
    }
    states, iam = boto3.client("stepfunctions", **options), boto3.client("iam", **options)
    name = "map-failure-repro-" + uuid.uuid4().hex[:12]
    machines, execution = [], None
    role = iam.create_role(
        RoleName=name,
        AssumeRolePolicyDocument=json.dumps({
            "Version": "2012-10-17", "Statement": [{
                "Effect": "Allow", "Principal": {"Service": "states.amazonaws.com"},
                "Action": "sts:AssumeRole",
            }],
        }),
    )["Role"]["Arn"]
    try:
        child = states.create_state_machine(
            name=name + "-child", roleArn=role,
            definition=json.dumps({
                "StartAt": "Fail", "States": {
                    "Fail": {"Type": "Fail", "Error": "ReproFailure", "Cause": "intentional failure"},
                },
            }),
        )["stateMachineArn"]
        machines.append(child)
        iam.put_role_policy(
            RoleName=name, PolicyName="NestedWorkflow",
            PolicyDocument=json.dumps({
                "Version": "2012-10-17", "Statement": [{
                    "Effect": "Allow",
                    "Action": ["states:StartExecution", "states:DescribeExecution", "states:StopExecution"],
                    "Resource": [child, child.replace(":stateMachine:", ":execution:") + ":*"],
                }, {
                    "Effect": "Allow",
                    "Action": ["events:PutTargets", "events:PutRule", "events:DescribeRule"],
                    "Resource": child.split(":stateMachine:")[0].replace(":states:", ":events:")
                    + ":rule/StepFunctionsGetEventsForStepFunctionsExecutionRule",
                }],
            }),
        )
        definition = {
            "StartAt": "Map", "States": {
                "Map": {
                    "Type": "Map", "ItemsPath": "$.items",
                    "Iterator": {
                        "StartAt": "Nested", "States": {
                            "Nested": {
                                "Type": "Task", "Resource": "arn:aws:states:::states:startExecution.sync:2",
                                "Parameters": {"StateMachineArn": child, "Input": {}}, "End": True,
                            },
                        },
                    },
                    "Catch": [{"ErrorEquals": ["States.TaskFailed"], "ResultPath": "$.error", "Next": "Caught"}],
                    "Next": "UnexpectedSuccess",
                },
                "Caught": {"Type": "Succeed"},
                "UnexpectedSuccess": {"Type": "Fail", "Error": "NestedFailureWasLost"},
            },
        }
        parent = states.create_state_machine(
            name=name + "-parent", roleArn=role, definition=json.dumps(definition),
        )["stateMachineArn"]
        machines.append(parent)
        execution = states.start_execution(
            stateMachineArn=parent, input=json.dumps({"items": [{}]}),
        )["executionArn"]
        deadline = time.monotonic() + 60
        while True:
            result = states.describe_execution(executionArn=execution)
            if result["status"] != "RUNNING" or time.monotonic() >= deadline:
                break
            time.sleep(0.5)
        report = {key: result[key] for key in ("status", "error", "cause", "output") if key in result}
        print(json.dumps(report, indent=2), flush=True)
        assert result["status"] == "SUCCEEDED", report
        output = json.loads(result["output"])
        assert output["error"]["Error"] == "States.TaskFailed", output
        assert "ReproFailure" in output["error"]["Cause"], output
    finally:
        for machine in reversed(machines):
            for row in states.list_executions(stateMachineArn=machine, statusFilter="RUNNING")["executions"]:
                states.stop_execution(executionArn=row["executionArn"], error="ReproducerCleanup")
            states.delete_state_machine(stateMachineArn=machine)
        for policy in iam.list_role_policies(RoleName=name)["PolicyNames"]:
            iam.delete_role_policy(RoleName=name, PolicyName=policy)
        iam.delete_role(RoleName=name)
        print(json.dumps({"cleanup": "Owned executions stopped, state machines deleted, role deleted"}), flush=True)


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--endpoint-url", default="http://127.0.0.1:4566")
    run(parser.parse_args().endpoint_url)

[AndreKurait]

Retested on 2026-10-11 against a fresh, unmodified localstack/localstack-pro:dev image, reporting Pro 2026.10.0.dev102 on Linux arm64. This still reproduces.

The child workflow intentionally fails. The parent inline Map invokes it with states:startExecution.sync:2 and catches States.TaskFailed, but the parent instead finishes FAILED with States.Runtime:

Custom Error Names MUST NOT begin with the prefix 'States.', got 'States.TaskFailed'.

This was a public IAM/Step Functions API reproducer in a separate stock container, with no source patches, extensions, or Docker socket mount. The disposable executions, state machines, role and container were cleaned up afterward.

Resolved image index: sha256:32adad290f38267baf073c8d519addfeee2dced2d9d68d3d28666cce88735bf7; arm64 image ID: sha256:c64ee0830b70bf09e2c58122b128e70ca44058a28d52caf1bcfa448f2fdf7ca5.

[EddEcho]

Hi @AndreKurait Thanks for retesting. We were able to reproduce this on our side as well, and it’s now with our engineering team for review. We’ll update this thread once a fix is available so you can test it.