{"record":{"id":"89a524fcab0cec79","repo":"hyperledger/fabric","slug":"failed-to-unmarshal-new-etcdraft-metadata-configur","errorCode":null,"errorMessage":"failed to unmarshal new etcdraft metadata configuration","messagePattern":"failed to unmarshal new etcdraft metadata configuration","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"orderer/consensus/etcdraft/chain.go","lineNumber":1502,"sourceCode":"\n\tif oldOrdererConfig == nil {\n\t\tc.logger.Panic(\"Programming Error: ValidateConsensusMetadata called with nil old channel config\")\n\t\treturn nil\n\t}\n\n\tif oldOrdererConfig.ConsensusMetadata() == nil {\n\t\tc.logger.Panic(\"Programming Error: ValidateConsensusMetadata called with nil old metadata\")\n\t\treturn nil\n\t}\n\n\toldMetadata := &etcdraft.ConfigMetadata{}\n\tif err := proto.Unmarshal(oldOrdererConfig.ConsensusMetadata(), oldMetadata); err != nil {\n\t\tc.logger.Panicf(\"Programming Error: Failed to unmarshal old etcdraft consensus metadata: %v\", err)\n\t}\n\n\tnewMetadata := &etcdraft.ConfigMetadata{}\n\tif err := proto.Unmarshal(newOrdererConfig.ConsensusMetadata(), newMetadata); err != nil {\n\t\treturn errors.Wrap(err, \"failed to unmarshal new etcdraft metadata configuration\")\n\t}\n\n\tverifyOpts, err := createX509VerifyOptions(newOrdererConfig)\n\tif err != nil {\n\t\treturn errors.Wrapf(err, \"failed to create x509 verify options from old and new orderer config\")\n\t}\n\n\tif err := VerifyConfigMetadata(newMetadata, verifyOpts); err != nil {\n\t\treturn errors.Wrap(err, \"invalid new config metadata\")\n\t}\n\n\tif newChannel {\n\t\t// check if the consenters are a subset of the existing consenters (system channel consenters)\n\t\tset := ConsentersToMap(oldMetadata.GetConsenters())\n\t\tfor _, c := range newMetadata.GetConsenters() {\n\t\t\tif !set.Exists(c) {\n\t\t\t\treturn errors.New(\"new channel has consenter that is not part of system consenter set\")\n\t\t\t}","sourceCodeStart":1484,"sourceCodeEnd":1520,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/orderer/consensus/etcdraft/chain.go#L1484-L1520","documentation":"Returned when the new channel config's consensus metadata cannot be unmarshaled into an etcdraft.ConfigMetadata protobuf. Unlike the old-metadata failure (which panics as a programming error), a bad NEW config is treated as a user configuration error and wrapped with this message.","triggerScenarios":"A config update's ConsensusMetadata field contains bytes that are not a valid etcdraft ConfigMetadata — hand-edited or wrongly generated consensus metadata during raft membership changes or consensus-type migration.","commonSituations":"Manually editing consensus metadata in the channel config; using configtxlator output from a different Fabric version; corrupted update envelope; consenters/metadata built by incompatible tooling.","solutions":["Regenerate the consensus metadata from the canonical configtx.yaml / configtxlator pipeline instead of hand-editing bytes.","Decode the metadata with 'configtxlator proto_decode --type etcdraft.ConfigMetadata' to inspect the corruption.","Ensure the tooling and Fabric versions used to produce the update match the running orderers.","Rebuild the config update, re-sign, and resubmit."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"md := &etcdraft.ConfigMetadata{}\nif err := proto.Unmarshal(newCfg.ConsensusMetadata, md); err != nil {\n    return fmt.Errorf(\"invalid etcdraft ConfigMetadata: %w\", err)\n}\nif len(md.Consenters) == 0 { return errors.New(\"no consenters in metadata\") }","typeGuard":null,"tryCatchPattern":"if strings.Contains(err.Error(), \"failed to unmarshal new etcdraft metadata configuration\") {\n    return regenerateConsensusMetadataViaConfigtxlator()\n}","preventionTips":["Generate consensus metadata with configtxlator only.","Match Fabric tooling versions with running orderers.","Decode-and-inspect metadata before each config update.","Never edit consensus metadata bytes manually."],"tags":["hyperledger-fabric","etcdraft","config-update","unmarshal"],"backgroundTag":"protobuf-unmarshal-failed","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"}