Class DynamoDbStalePositionReasonCodes
Provides standardized reason codes for DynamoDB Streams stale position scenarios.
public static class DynamoDbStalePositionReasonCodes
- Inheritance
-
DynamoDbStalePositionReasonCodes
- Inherited Members
Remarks
These codes categorize why a DynamoDB Stream position became invalid. DynamoDB Streams retain data for 24 hours. Common stale position scenarios include:
- Iterator expiry (iterators expire after 15 minutes of inactivity)
- Sequence number beyond the trim horizon (data older than 24 hours)
- Shard closure due to splits or merges
- Stream disabled or table deleted
These codes are used in ReasonCode to enable consistent logging, alerting, and handling across different stale position scenarios.
Fields
IteratorExpired
The shard iterator has expired (15 minutes without use).
public const string IteratorExpired = "DYNAMODB_ITERATOR_EXPIRED"
Field Value
Remarks
DynamoDB shard iterators are valid for up to 15 minutes. If the iterator is not used
within this window, it expires and a new iterator must be obtained.
AWS Exception: ExpiredIteratorException.
Common causes:
- Consumer paused or stopped for more than 15 minutes
- Network interruption causing iterator timeout
- Processing delay exceeding iterator lifetime
ShardClosed
The shard has been closed and is no longer available.
public const string ShardClosed = "DYNAMODB_SHARD_CLOSED"
Field Value
Remarks
Shards can close when they split, merge, or when the stream is disabled. A closed shard should be read to completion, then replaced with child shards.
Common causes:
- Shard split due to increased write throughput
- Shard merge during table capacity reduction
- Stream disabled on the table
ShardNotFound
The shard was not found, possibly due to split or stream recreation.
public const string ShardNotFound = "DYNAMODB_SHARD_NOT_FOUND"
Field Value
Remarks
This occurs when attempting to access a shard that no longer exists.
The shard may have split into child shards or been deleted.
AWS Exception: ResourceNotFoundException.
Common causes:
- Shard split created new child shards
- Stream was disabled and re-enabled
- Invalid or corrupted shard ID
StreamDisabled
The stream has been disabled on the table.
public const string StreamDisabled = "DYNAMODB_STREAM_DISABLED"
Field Value
Remarks
When a stream is disabled, it can no longer be read. Re-enabling streams creates a new stream with a new ARN.
Common causes:
- Stream explicitly disabled via console or API
- Table configuration changed
StreamNotFound
The stream was not found, possibly disabled or table deleted.
public const string StreamNotFound = "DYNAMODB_STREAM_NOT_FOUND"
Field Value
Remarks
This occurs when the stream is no longer available for the table.
AWS Exception: ResourceNotFoundException.
Common causes:
- Stream disabled on the DynamoDB table
- Table deleted
- Stream ARN is invalid or from a different region
TrimmedData
The sequence number is beyond the stream's trim horizon (older than 24 hours).
public const string TrimmedData = "DYNAMODB_TRIMMED_DATA"
Field Value
Remarks
DynamoDB Streams retain records for 24 hours. If a consumer falls behind
by more than 24 hours, the sequence number is no longer available.
AWS Exception: TrimmedDataAccessException.
Common causes:
- Consumer offline for more than 24 hours
- Processing lag exceeding retention window
- Saved checkpoint older than 24 hours
Unknown
The reason for the stale position could not be determined.
public const string Unknown = "DYNAMODB_UNKNOWN"
Field Value
Remarks
This is used when the specific cause cannot be identified from the AWS error or when an unexpected error occurs during position validation.
Methods
FromErrorMessage(string?)
Determines the reason code from a DynamoDB Streams error message pattern.
public static string FromErrorMessage(string? errorMessage)
Parameters
errorMessagestringThe DynamoDB Streams error message.
Returns
- string
The corresponding reason code.
Remarks
This method provides fallback detection when exception types are not available by analyzing common error message patterns.
FromExceptionType(string?)
Determines the reason code from an AWS exception type name.
public static string FromExceptionType(string? exceptionTypeName)
Parameters
exceptionTypeNamestringThe name of the AWS exception type.
Returns
- string
The corresponding reason code.
Remarks
AWS DynamoDB Streams exception types relevant to stale positions:
- ExpiredIteratorException - Iterator expired
- TrimmedDataAccessException - Data beyond trim horizon
- ResourceNotFoundException - Stream/shard not found