Table of Contents

Class CdcReasonCodes

Namespace
Excalibur.Cdc
Assembly
Excalibur.Cdc.dll

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

reasonCode string

The 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.