Class MongoDbStalePositionReasonCodes
Provides standardized reason codes for MongoDB CDC stale position scenarios.
public static class MongoDbStalePositionReasonCodes
- Inheritance
-
MongoDbStalePositionReasonCodes
- Inherited Members
Remarks
These codes categorize why a change stream resume token became invalid in MongoDB. Unlike Postgres logical replication slots, MongoDB stale positions typically occur due to:
- Resume token no longer available in oplog
- Collection dropped or renamed
- Shard migration invalidating the stream
- Change stream explicitly invalidated
These codes are used in CdcPositionResetEventArgs.ReasonCode to enable consistent
logging, alerting, and handling across different stale position scenarios.
Fields
CollectionDropped
The collection being watched was dropped.
public const string CollectionDropped = "MONGODB_COLLECTION_DROPPED"
Field Value
Remarks
This occurs when the source collection no longer exists. MongoDB error code 26 (NamespaceNotFound).
Common causes:
- Collection explicitly dropped
- Database dropped
- Collection recreated (different UUID)
CollectionRenamed
The collection being watched was renamed.
public const string CollectionRenamed = "MONGODB_COLLECTION_RENAMED"
Field Value
Remarks
This occurs when the source collection has been renamed. MongoDB error code 73 (InvalidNamespace).
Common causes:
- Collection renamed via renameCollection command
- Namespace changed during migration
InvalidResumeToken
The resume token format or content is invalid.
public const string InvalidResumeToken = "MONGODB_INVALID_RESUME_TOKEN"
Field Value
Remarks
This occurs when the resume token cannot be parsed or is corrupted. MongoDB error code 286 (ChangeStreamFatalError).
Common causes:
- Token serialization/deserialization error
- Token from incompatible MongoDB version
- Manual token modification or corruption
ResumeTokenNotFound
The resume token is no longer available in the oplog.
public const string ResumeTokenNotFound = "MONGODB_RESUME_TOKEN_NOT_FOUND"
Field Value
Remarks
This occurs when the oplog has rolled over and the position corresponding to the resume token has been overwritten. MongoDB error code 136 (ChangeStreamHistoryLost).
Common causes:
- Oplog size too small for change stream consumption rate
- Consumer offline for too long
- High write volume causing rapid oplog rotation
ShardMigration
The change stream was invalidated due to shard migration.
public const string ShardMigration = "MONGODB_SHARD_MIGRATION"
Field Value
Remarks
This occurs in sharded clusters when the chunk containing the resume position has been migrated. MongoDB error code 133 (StaleShardVersion).
Common causes:
- Chunk migration during balancing
- Shard removed from cluster
- Collection resharded
StreamInvalidated
The change stream received an explicit invalidate event.
public const string StreamInvalidated = "MONGODB_STREAM_INVALIDATED"
Field Value
Remarks
This occurs when MongoDB sends an invalidate event, signaling that the change stream is no longer valid and must be restarted.
Common causes:
- Collection dropped while stream active
- Database dropped while stream active
- dropDatabase command executed
Unknown
The reason for the stale position could not be determined.
public const string Unknown = "MONGODB_UNKNOWN"
Field Value
Remarks
This is used when the specific cause cannot be identified from the MongoDB error or when an unexpected error occurs during position validation.
Methods
FromErrorCode(int)
Determines the reason code from a MongoDB error code.
public static string FromErrorCode(int errorCode)
Parameters
errorCodeintThe MongoDB error code.
Returns
- string
The corresponding reason code.
Remarks
MongoDB error codes relevant to change streams:
- 136 - ChangeStreamHistoryLost (resume token not in oplog)
- 286 - ChangeStreamFatalError (invalid resume token)
- 26 - NamespaceNotFound (collection dropped)
- 73 - InvalidNamespace (collection renamed)
- 133 - StaleShardVersion (shard migration)
FromErrorMessage(string?)
Determines the reason code from a MongoDB error message pattern.
public static string FromErrorMessage(string? errorMessage)
Parameters
errorMessagestringThe MongoDB error message.
Returns
- string
The corresponding reason code.
Remarks
This method provides fallback detection when error codes are not available by analyzing common error message patterns.