{"record":{"id":"2beb64d6958fe0f3","repo":"hyperledger/fabric","slug":"failed-to-unmarshal-channel-metadata","errorCode":null,"errorMessage":"failed to unmarshal channel metadata","messagePattern":"failed to unmarshal channel metadata","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdoc_conv.go","lineNumber":243,"sourceCode":"\t\treturn nil, err\n\t}\n\treturn &version.Height{BlockNum: savepointDoc.BlockNum, TxNum: savepointDoc.TxNum}, nil\n}\n\nfunc encodeChannelMetadata(metadataDoc *channelMetadata) (*couchDoc, error) {\n\tmetadataJSON, err := json.Marshal(metadataDoc)\n\tif err != nil {\n\t\terr = errors.Wrap(err, \"failed to marshal channel metadata\")\n\t\tlogger.Errorf(\"%+v\", err)\n\t\treturn nil, err\n\t}\n\treturn &couchDoc{jsonValue: metadataJSON, attachments: nil}, nil\n}\n\nfunc decodeChannelMetadata(couchDoc *couchDoc) (*channelMetadata, error) {\n\tmetadataDoc := &channelMetadata{}\n\tif err := json.Unmarshal(couchDoc.jsonValue, &metadataDoc); err != nil {\n\t\terr = errors.Wrap(err, \"failed to unmarshal channel metadata\")\n\t\tlogger.Errorf(\"%+v\", err)\n\t\treturn nil, err\n\t}\n\treturn metadataDoc, nil\n}\n\ntype dataformatInfo struct {\n\tVersion string `json:\"Version\"`\n}\n\nfunc encodeDataformatInfo(dataFormatVersion string) (*couchDoc, error) {\n\tvar err error\n\tdataformatInfo := &dataformatInfo{\n\t\tVersion: dataFormatVersion,\n\t}\n\tdataformatInfoJSON, err := json.Marshal(dataformatInfo)\n\tif err != nil {\n\t\terr = errors.Wrapf(err, \"failed to marshal dataformatInfo [%#v]\", dataformatInfo)","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/ledger/kvledger/txmgmt/statedb/statecouchdb/couchdoc_conv.go#L225-L261","documentation":"decodeChannelMetadata parses the channel metadata JSON stored in CouchDB back into a channelMetadata struct. Failure means the stored metadata document is corrupt or not in the expected schema, wrapped as 'failed to unmarshal channel metadata'; readChannelMetadata then fails.","triggerScenarios":"readChannelMetadata fetches the channel metadata couchDoc and its jsonValue cannot be unmarshaled into channelMetadata (e.g. wrong field types, non-JSON content, wrong document retrieved).","commonSituations":"Manual modification of the metadata document in CouchDB, restoring databases from backups of a different Fabric version, or accidental overwrites by external tooling.","solutions":["Inspect and correct the channel metadata document in CouchDB (it should contain the data format version field)","Restore the state database from a valid backup","If unrecoverable, rebuild the ledger database so metadata is rewritten at open time"],"exampleFix":"// before (corrupt doc)\n{\"DataFormatVersion\": 2.5}\n// after\n{\"DataFormatVersion\": \"2.0\"}","handlingStrategy":"try-catch","validationCode":"func validChannelMetadataJSON(b []byte) bool {\n    var m struct{ DataFormatVersion string }\n    return json.Unmarshal(b, &m) == nil\n}","typeGuard":null,"tryCatchPattern":"md, err := decodeChannelMetadata(doc)\nif err != nil {\n    return nil, fmt.Errorf(\"channel metadata corrupt; restore DB from backup: %w\", err)\n}","preventionTips":["Never hand-edit channel metadata documents","Back up and restore the ledger DB as a consistent set","Pin the Fabric version when restoring state databases"],"tags":["json","unmarshalling","channel-metadata","fabric-ledger","couchdb"],"backgroundTag":"json-unmarshalling-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"}