vitessio/vitess · error

invalid NewMaxReplicationLagModuleConfig: %v

Error message

invalid NewMaxReplicationLagModuleConfig: %v

What it means

NewMaxReplicationLagModule wraps any validation failure returned by MaxReplicationLagModuleConfig.Verify() with this message. It means the supplied throttler replication-lag config failed structural validation (bad limits, rates, or increase/decrease parameters). The module cannot be constructed until the config is fixed.

Source

Thrown at go/vt/throttler/max_replication_lag_module.go:130

	// rateUpdateChan is the notification channel to tell the throttler when our
	// max rate calculation has changed. The field is immutable (set in Start().)
	rateUpdateChan chan<- struct{}

	// lagRecords buffers the replication lag records received by the HealthCheck
	// subscriber. ProcessRecords() will process them.
	lagRecords chan replicationLagRecord
	wg         sync.WaitGroup

	// results caches the results of the latest processed replication lag records.
	results *resultRing
}

// NewMaxReplicationLagModule will create a new module instance and set the
// initial max replication lag limit to maxReplicationLag.
func NewMaxReplicationLagModule(config MaxReplicationLagModuleConfig, actualRatesHistory *aggregatedIntervalHistory, nowFunc func() time.Time) (*MaxReplicationLagModule, error) {
	if err := config.Verify(); err != nil {
		return nil, fmt.Errorf("invalid NewMaxReplicationLagModuleConfig: %v", err)
	}
	rate := int64(ReplicationLagModuleDisabled)
	if config.MaxReplicationLagSec != ReplicationLagModuleDisabled {
		rate = config.InitialRate
	}

	m := &MaxReplicationLagModule{
		initialMaxReplicationLagSec: config.MaxReplicationLagSec,
		// Register "config" for a future config update.
		mutableConfig:      config,
		applyMutableConfig: true,
		currentState:       stateIncreaseRate,
		lastRateChange:     nowFunc(),
		memory:             newMemory(memoryGranularity, config.AgeBadRateAfter(), config.BadRateIncrease),
		lagRecords:         make(chan replicationLagRecord, 10),
		// Prevent an immediate increase of the initial rate.
		nextAllowedChangeAfterInit: nowFunc().Add(config.MaxDurationBetweenIncreases()),
		actualRatesHistory:         actualRatesHistory,

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Read the wrapped %v error to see which specific field failed Verify().
2. Set max_replication_lag_sec >= 2 and target_replication_lag_sec >= 1 with target <= max.
3. Ensure initial_rate >= 1 and max-increase/max-decrease values are positive per config docs.
4. If replication-lag throttling is unwanted, set MaxReplicationLagSec to ReplicationLagModuleDisabled instead of an invalid value.

Example fix

// before
config := throttler.MaxReplicationLagModuleConfig{
  MaxReplicationLagSec: 1, // invalid: must be >= 2
  TargetReplicationLagSec: 1,
  InitialRate: 1000000,
}
// after
config := throttler.MaxReplicationLagModuleConfig{
  MaxReplicationLagSec: 10,
  TargetReplicationLagSec: 5,
  InitialRate: 1000000,
}

if err := config.Verify(); err != nil {
    return fmt.Errorf("config rejected before construction: %w", err)
}
_ = throttler.NewMaxReplicationLagModule(config, history, nowFunc)

mod, err := throttler.NewMaxReplicationLagModule(config, history, nowFunc)
if err != nil {
    log.Warn("replication lag module disabled", slog.Any("error", err))
    return nil // fall back to no lag throttling
}

When it happens

Trigger: Calling NewMaxReplicationLagModule (directly, or via newThrottlerFromConfig/newThrottler) with a MaxReplicationLagModuleConfig that fails Verify(): e.g. MaxReplicationLagSec < 2, TargetReplicationLagSec < 1, InitialRate < 1, MaxIncrease <= 0, or target > max lag.

Common situations: Hand-writing throttler configs in vtctld/vreplication (e.g. vstreamer throttler settings), YAML/JSON with zero-valued fields because only some fields were set, copy-pasted configs from older Vitess versions where limits differed.

Related errors

• target_replication_lag_sec must not be higher than max_repli
• invalid max replication lag config: %w
• maxRate must be >= 0: %v
• ignoring higher good rate of %v because we assume that the k
• ignoring lower bad rate of %v because such a high degradatio

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/6e5a7737a1ac98b9. Report an issue: GitHub.