{"record":{"id":"64a0ab796f7036b9","repo":"hyperledger/fabric","slug":"failed-parsing-smartbft-configuration","errorCode":null,"errorMessage":"failed parsing smartbft configuration","messagePattern":"failed parsing smartbft configuration","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"orderer/consensus/smartbft/consenter.go","lineNumber":192,"sourceCode":"}\n\n// HandleChain returns a new Chain instance or an error upon failure\nfunc (c *Consenter) HandleChain(support consensus.ConsenterSupport, metadata *cb.Metadata) (consensus.Chain, error) {\n\tconsenters := support.SharedConfig().Consenters()\n\tconfigOptions, err := createSmartBftConfig(support.SharedConfig())\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tselfID, err := c.detectSelfID(consenters)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"without a system channel, a follower should have been created\")\n\t}\n\tc.Logger.Infof(\"Local consenter id is %d\", selfID)\n\n\tconfig, err := util.ConfigFromMetadataOptions(uint64(selfID), configOptions)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"failed parsing smartbft configuration\")\n\t}\n\tc.Logger.Debugf(\"SmartBFT-Go config: %+v\", config)\n\n\tconfigValidator := &ConfigBlockValidator{\n\t\tValidatingChannel:    support.ChannelID(),\n\t\tFilters:              c.Registrar,\n\t\tConfigUpdateProposer: c.Registrar,\n\t\tLogger:               c.Logger,\n\t}\n\n\tegressCommFactory := func(runtimeConfig *atomic.Value, channelId string, comm cluster.Communicator) EgressComm {\n\t\tchannelDecorator := zap.String(\"channel\", channelId)\n\t\treturn &Egress{\n\t\t\tRuntimeConfig: runtimeConfig,\n\t\t\tChannel:       channelId,\n\t\t\tLogger:        flogging.MustGetLogger(\"orderer.consensus.smartbft.egress\").With(channelDecorator),\n\t\t\tRPC: &cluster.RPC{\n\t\t\t\tLogger:        flogging.MustGetLogger(\"orderer.consensus.smartbft.rpc\").With(channelDecorator),","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/orderer/consensus/smartbft/consenter.go#L174-L210","documentation":"HandleChain parses the SmartBFT metadata options (from the channel config block's ConsensusMetadata) via util.ConfigFromMetadataOptions to build the SmartBFT-Go runtime config. If that parsing/validation fails, the error is wrapped as 'failed parsing smartbft configuration' and the chain fails to start.","triggerScenarios":"The channel config block contains a ConsensusMetadata whose options (e.g. request batch max bytes exceeding block batch size, malformed/invalid smartbft options) violate ConfigFromMetadataOptions invariants, or the metadata is missing/corrupted in the genesis/join block.","commonSituations":"Channel created with configtxgen output where SmartBFT Options were misconfigured (RequestBatchMaxBytes > BlockBatchMaxBytes); a config block edited by hand corrupting consensus metadata; mixing fabric versions where the metadata schema changed; joining with a truncated config block.","solutions":["Regenerate the channel genesis/config block with configtxgen and correct SmartBFT Options in configtx.yaml (ensure RequestMaxBytes <= BatchSize.MaxMessageCount-compatible limits)","Inspect the wrapped inner error from ConfigFromMetadataOptions in the logs for the exact violated constraint","Validate the profile's Consensus section against the fabric version you run; upgrade configtxgen if the metadata format changed","Re-create the channel (or submit a config update fixing the Options) with valid consensus metadata"],"exampleFix":"// before (configtx.yaml)\nConsenterMapping: ...\nOptions:\n  RequestBatchMaxBytes: 10MB   # larger than block batch max\n\n// after\nOptions:\n  RequestBatchMaxBytes: 1MB    # must fit within BlockBatch limits","handlingStrategy":"validation","validationCode":"// Validate SmartBFT options before channel creation\nif cfg.Options.RequestBatchMaxBytes > cfg.BatchSizeAbsoluteMaxBytes {\n    return errors.New(\"RequestBatchMaxBytes exceeds block batch limits; fix configtx.yaml Options\")\n}\n// And sanity-check the generated genesis block's consensus metadata decodes\nvar md consensus.Metadata\nif err := proto.Unmarshal(genesisBlock.Metadata, &md); err != nil {\n    return err\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate SmartBFT Options in configtx.yaml against the fabric version's limits","Regenerate genesis blocks with a matching-version configtxgen","Never hand-edit marshaled config blocks; always go through configtxlator","Test channel creation in CI with the same profiles used in production"],"tags":["fabric","smartbft","config","genesis-block"],"backgroundTag":"consensus-metadata-invalid","analyzedSha":"2736b63f8fd5932511d56fe68b7039d15977f7f6","analyzedAt":"2026-09-04T08:52:36.465Z","contentChangedAt":"2026-09-04T08:52:36.465Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}