Class CdcReasonCodes
Provides standardized reason codes for CDC stale position scenarios across all providers.
public static class CdcReasonCodes
- Inheritance
-
CdcReasonCodes
- Inherited Members
Remarks
These codes are used in ReasonCode to categorize
why a CDC position became invalid. Providers may use these common codes or define
provider-specific codes with appropriate prefixes (e.g., MONGODB_, COSMOSDB_).
Common stale position scenarios include:
- Position purged by cleanup/retention (SQL Server CDC, Postgres WAL)
- Token expiration (MongoDB oplog, CosmosDB change feed)
- Database restore or replication slot deletion
- CDC/change stream configuration changes
Fields
BackupRestore
The position is invalid after a database backup and restore operation.
public const string BackupRestore = "BACKUP_RESTORE"
Field Value
Remarks
This occurs when a database is restored from a backup taken before the saved position, or when a lower environment receives a copy of production data with different CDC history.
CdcReenabled
CDC or change tracking was disabled and re-enabled, invalidating existing positions.
public const string CdcReenabled = "CDC_REENABLED"
Field Value
Remarks
When CDC is disabled and re-enabled, all capture instances are recreated and previous position values are no longer valid. Examples:
- SQL Server: sys.sp_cdc_disable_db and sys.sp_cdc_enable_db
- Postgres: Replication slot dropped and recreated
PartitionChanged
A partition split or shard migration invalidated the position.
public const string PartitionChanged = "PARTITION_CHANGED"
Field Value
Remarks
Distributed databases may reorganize partitions:
- CosmosDB: Partition split due to storage growth
- MongoDB: Shard migration in sharded clusters
- DynamoDB: Shard split in DynamoDB Streams
PositionOutOfRange
The position is outside the valid range of available change data.
public const string PositionOutOfRange = "POSITION_OUT_OF_RANGE"
Field Value
Remarks
A general error when the position falls outside the min/max range available in the change tables. Provider-specific examples:
- SQL Server: Error 22037 or 22029 (LSN out of range)
- Postgres: WAL position before consistent point
PositionPurged
The position was purged by a cleanup or retention process.
public const string PositionPurged = "POSITION_PURGED"
Field Value
Remarks
This is the most common reason for stale positions. Examples:
- SQL Server: CDC cleanup job (sys.sp_cdc_cleanup_change_tables)
- Postgres: WAL segments recycled past retention
- MongoDB: Oplog rolled over before consumption
- CosmosDB: Continuation token expired (7-day retention)
SourceDropped
The capture instance, collection, or table no longer exists.
public const string SourceDropped = "SOURCE_DROPPED"
Field Value
Remarks
This occurs when the source of change data has been dropped:
- SQL Server: Capture instance dropped
- MongoDB: Collection dropped
- CosmosDB: Container deleted
- DynamoDB: Table deleted or stream disabled
SourceRenamed
The source was renamed, invalidating the position.
public const string SourceRenamed = "SOURCE_RENAMED"
Field Value
Remarks
This occurs when the collection, table, or namespace has been renamed:
- MongoDB: Collection renamed
- Postgres: Table renamed
StreamInvalidated
The change stream was explicitly invalidated.
public const string StreamInvalidated = "STREAM_INVALIDATED"
Field Value
Remarks
The change stream sent an explicit invalidation event:
- MongoDB: Invalidate event in change stream
- Firestore: Listen target removed
TokenExpired
The change stream or resume token has expired.
public const string TokenExpired = "TOKEN_EXPIRED"
Field Value
Remarks
Document databases use tokens with finite lifetimes:
- MongoDB: Resume token no longer in oplog (error 136)
- CosmosDB: Continuation token expired (HTTP 410)
- DynamoDB: Shard iterator expired (24-hour lifetime)
Unknown
The reason for the stale position could not be determined.
public const string Unknown = "UNKNOWN"
Field Value
Remarks
This is used when the specific cause cannot be identified from the provider error or when an unexpected error occurs during position validation.
Methods
IsRecoverable(string?)
Determines if a reason code indicates a recoverable scenario.
public static bool IsRecoverable(string? reasonCode)
Parameters
reasonCodestringThe reason code to check.
Returns
- bool
true if the scenario is typically recoverable by resetting to earliest or latest position; otherwise, false.
Remarks
Recoverable scenarios are those where the consumer can safely resume from a different position. Non-recoverable scenarios typically require manual intervention.