[Bug]: [Bug]: ParamValidationError: Invalid length for parameter CheckpointToken during context.wait()

[Lmex89vexi]

Expected Behavior

Description
When suspending an execution using context.wait(), the background state-syncing thread crashes with a botocore.exceptions.ParamValidationError.

The lambda_service.py client appears to be passing an empty string ("") or invalid zero-length value for the CheckpointToken parameter during the checkpoint_durable_execution API call. Boto3 validation requires this parameter to have a minimum length of 1 if it is included in the payload.

Actual Behavior

Actual Behavior
The checkpoint fails immediately during Boto3 parameter validation before the network request is made, crashing the background thread.

Environment Details
SDK Version: 1.5.0

Python Version: 3.13

Execution Environment: AWS Lambda

OS: Amazon Linux 2023 (Lambda standard runtime)

Steps to Reproduce

Steps to Reproduce
Initialize a durable execution inside an AWS Lambda function running the python3.13 runtime.

Invoke context.wait(Duration.from_seconds(35)) (or similar duration).

The SDK's background checkpointing process triggers lambda_service.checkpoint().

Observe the ParamValidationError in CloudWatch logs and the resulting BackgroundThreadError.

Expected Behavior
The SDK should successfully checkpoint the execution state. If a CheckpointToken is not yet available or is empty, the SDK should omit the parameter from the checkpoint_durable_execution kwargs rather than passing a zero-length string.

SDK Version

1.5.0

Python Version

3.13

Is this a regression?

No

Last Working Version

No response

Additional Context

No response

[zhongkechen]

Thanks for reporting this. We traced the checkpoint-token lifecycle and this does appear to be a valid SDK bug, but the proposed fix should be adjusted.

CheckpointToken is a required input to CheckpointDurableExecution with a minimum length of 1. Omitting it from a subsequent request would therefore fail botocore validation with a missing-required-parameter error.

The backend can legitimately return an empty/null response CheckpointToken when that checkpoint completes the execution, because there is no next checkpoint token. The Python SDK currently mishandles that terminal response:

1. CheckpointOutput.from_dict() maps an absent response token to "".
2. The checkpoint batching loop unconditionally installs the response token as its current token.
3. If another queued or later checkpoint is processed, the SDK sends CheckpointToken="", producing the reported ParamValidationError before a request reaches the service.

The correct behavior is to treat a missing/empty response token as a terminal signal, stop processing or issuing further checkpoints, and settle any queued waiters appropriately. The SDK should not make another checkpoint request with the token omitted. context.wait() can expose this lifecycle race, but the underlying problem is not specific to waits.

For comparison, the TypeScript SDK only replaces its current checkpoint token when the response contains a truthy token, which avoids converting a terminal response into an empty request token. Full terminal handling in Python would be preferable to merely retaining the consumed token.

[ayushiahjolia]

We are tracking the fix under #43