What causes "config validation failed" in hyperledger/fabric?

Read the wrapped underlying error to see which validation invariant failed and adjust the offending option

config validation failed

Error message

config validation failed

What it means

After parsing all metadata options into a types.Configuration, ConfigFromMetadataOptions calls config.Validate(); if any invariant is violated (inconsistent timeouts, zero thresholds, etc.) the error is wrapped as 'config validation failed'. This guards against syntactically valid but semantically unsafe BFT configurations before the chain is started.

Source

Thrown at orderer/consensus/smartbft/util/util.go:68

		return config, errors.Wrap(err, "bad config metadata option LeaderHeartbeatTimeout")
	}
	config.LeaderHeartbeatCount = options.LeaderHeartbeatCount
	if config.CollectTimeout, err = time.ParseDuration(options.CollectTimeout); err != nil {
		return config, errors.Wrap(err, "bad config metadata option CollectTimeout")
	}
	config.SyncOnStart = options.SyncOnStart
	config.SpeedUpViewChange = options.SpeedUpViewChange

	if options.LeaderRotation != smartbft.Options_ROTATION_ON {
		config.LeaderRotation = false
		config.DecisionsPerLeader = 0
	} else {
		config.LeaderRotation = true
		config.DecisionsPerLeader = options.DecisionsPerLeader
	}

	if err = config.Validate(); err != nil {
		return config, errors.Wrap(err, "config validation failed")
	}

	if options.RequestMaxBytes == 0 {
		config.RequestMaxBytes = config.RequestBatchMaxBytes
	} else {
		config.RequestMaxBytes = options.RequestMaxBytes
	}

	return config, nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

Read the wrapped underlying error to see which validation invariant failed and adjust the offending option
Ensure timeout hierarchy holds (e.g. resend interval < view change timeout, heartbeat timeouts consistent)
Set all numeric options to nonzero sane values matching the official BFT config guidance
Use `inspect` to validate the config block before committing the update

Example fix

// before
"ViewChangeResendInterval": "30s",
"ViewChangeTimeout": "20s" // validation fails: resend >= timeout
// after
"ViewChangeResendInterval": "10s",
"ViewChangeTimeout": "20s"

Defensive patterns

Strategy: validation

Validate before calling

cfg, err := util.ConfigFromMetadataOptions(selfID, opts)
if err != nil { return fmt.Errorf("options fail validation: %w", err) }
// additionally: resend < viewChange, heartbeat count > 0 checks

Try / catch

cfg, err := util.ConfigFromMetadataOptions(selfID, opts)
if err != nil {
  if strings.Contains(err.Error(), "config validation failed") {
    return fmt.Errorf("BFT options semantically invalid, fix options and resubmit: %w", err)
  }
  return err
}

Prevention

Change one BFT timeout at a time and re-validate relationships
Keep documented default values unless tuning is required
Use inspect to validate the whole config block pre-commit
Don't copy Raft timing options into BFT metadata

When it happens

Trigger: Orderer start, channel config commit, or `inspect` when individual durations parse but violate validation rules — e.g. ViewChangeResendInterval >= ViewChangeTimeout, LeaderHeartbeatCount 0, RequestBatchMaxCount 0, or timeout hierarchy inversions.

Common situations: Operator tuned one timeout without respecting required relationships to the others, copied options from a Raft config, or a tool generated options with zero-value numeric fields.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/1696e674bb9476bf. Report an issue: GitHub.