Table of Contents

Class DynamoDbStalePositionReasonCodes

Namespace
Excalibur.Cdc.DynamoDb
Assembly
Excalibur.Cdc.DynamoDb.dll

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

errorMessage string

The 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

exceptionTypeName string

The 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