Table of Contents

Class MongoDbStalePositionReasonCodes

Namespace
Excalibur.Cdc.MongoDB
Assembly
Excalibur.Cdc.MongoDB.dll

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

string

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

string

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

string

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

string

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

string

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

string

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

string

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

errorCode int

The 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

errorMessage string

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