bug: Step Functions JSONPath filter projection loses its array shape for zero or one match

[AndreKurait]

Additional version check — 2026-10-08

Still reproduced: the nine-case projection/intrinsic matrix has the same results, including lost zero/singleton collection shape and the incorrect singleton nested-array result.

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

The following selection in a Pass state's Parameters loses the outer collection when a JSONPath filter matches zero or one nested field:

{
  "matches.$": "$.items[?(@.key == 'keep')].payload.value",
  "first.$": "States.ArrayGetItem($.items[?(@.key == 'keep')].payload.value, 0)"
}

Selected values	Expected projection	Observed projection
No matches	[]	States.Runtime missing-path error
One string	["one"]	"one"
Two strings	["one", "two"]	["one", "two"]
One array	[["nested"]]	["nested"]
One null	[null]	null

With ArrayGetItem added, the singleton string and null cases fail. The singleton array case silently produces "nested" instead of ["nested"]. The two-string case works.

The attached script runs nine public API cases using two Pass-only Standard workflows on a fresh, unmodified LocalStack container. It does not test index zero of an empty array.

Expected behavior

A filter projection should retain its collection shape for zero, one, and multiple matches. ArrayGetItem should then select an element without losing that element's type. A one-element array containing an array or null is particularly useful for distinguishing projection cardinality from the selected value's type.

References: Step Functions JSONPath and array intrinsics.

I have not run these cases on live AWS. The expected results are the intended JSONPath collection semantics; please flag any expression here that LocalStack considers outside supported Step Functions syntax. The report concerns filter projections followed by object fields, not all reference-path or literal-index behavior.

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_filter_arrays.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_filter_arrays.py

"""Check JSONPath filter projection shape through ordinary local Step Functions APIs."""
import argparse
import json
import time
import uuid
from urllib.parse import urlsplit

import boto3
from botocore.config import Config


FILTER = "$.items[?(@.key == 'keep')].payload.value"


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 = "filter-array-repro-" + uuid.uuid4().hex[:12]
    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"]
    machines, results = [], []
    try:
        for with_intrinsic in (False, True):
            parameters = {"matches.$": FILTER}
            if with_intrinsic:
                parameters["first.$"] = f"States.ArrayGetItem({FILTER}, 0)"
            machine = states.create_state_machine(
                name=name + ("-intrinsic" if with_intrinsic else "-projection"), roleArn=role,
                definition=json.dumps({"StartAt": "Select", "States": {
                    "Select": {"Type": "Pass", "Parameters": parameters, "End": True},
                }}),
            )["stateMachineArn"]
            machines.append(machine)
            for values in ([], ["one"], ["one", "two"], [["nested"]], [None]):
                if with_intrinsic and not values:
                    continue
                input_value = {"items": [{"key": "skip", "payload": {"value": "excluded"}}]
                               + [{"key": "keep", "payload": {"value": value}} for value in values]}
                execution = states.start_execution(
                    stateMachineArn=machine, input=json.dumps(input_value))["executionArn"]
                deadline = time.monotonic() + 30
                while True:
                    result = states.describe_execution(executionArn=execution)
                    if result["status"] != "RUNNING" or time.monotonic() >= deadline:
                        break
                    time.sleep(0.05)
                expected = {"matches": values}
                if with_intrinsic:
                    expected["first"] = values[0]
                observed = json.loads(result["output"]) if "output" in result else None
                results.append({
                    "intrinsic": with_intrinsic, "input_values": values,
                    "expected": expected, "observed": observed,
                    "status": result["status"],
                    "error": result.get("error"), "cause": result.get("cause"),
                    "passed": result["status"] == "SUCCEEDED" and observed == expected,
                })
        print(json.dumps({"results": results}, indent=2), flush=True)
    finally:
        for machine in reversed(machines):
            for execution in states.list_executions(
                    stateMachineArn=machine, statusFilter="RUNNING")["executions"]:
                states.stop_execution(executionArn=execution["executionArn"], error="ReproducerCleanup")
            states.delete_state_machine(stateMachineArn=machine)
        iam.delete_role(RoleName=name)
        print(json.dumps({"cleanup": "Owned workflows and role deleted"}), flush=True)
    assert all(row["passed"] for row in results), "Filtered results lost their array shape"


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)

[ryan-berke]

Hi @AndreKurait, thanks for raising this with us. I have escalated this issue to my engineers for a fix, so I will let you know as soon as we are ready for you to give it a try again. Please let me know if you have any questions or other issues in the meantime.

[ryan-berke]

Hi @AndreKurait , this is now fixed in the localstack/localstack:dev image. Please give this a try again and let us know if you have any further issues, thank you!