{"record":{"id":"686b5d6ab556fbff","repo":"hyperledger/fabric","slug":"error-while-unmarshalling-additional-metadata","errorCode":null,"errorMessage":"error while unmarshalling additional metadata","messagePattern":"error while unmarshalling additional metadata","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/ledger/kvledger/snapshot.go","lineNumber":83,"sourceCode":"type SnapshotMetadata struct {\n\t*SnapshotSignableMetadata\n\t*snapshotAdditionalMetadata\n}\n\ntype SnapshotMetadataJSONs struct {\n\tsignableMetadata   string\n\tadditionalMetadata string\n}\n\nfunc (j *SnapshotMetadataJSONs) ToMetadata() (*SnapshotMetadata, error) {\n\tmetadata := &SnapshotSignableMetadata{}\n\tif err := json.Unmarshal([]byte(j.signableMetadata), metadata); err != nil {\n\t\treturn nil, errors.Wrap(err, \"error while unmarshalling signable metadata\")\n\t}\n\n\tadditionalMetadata := &snapshotAdditionalMetadata{}\n\tif err := json.Unmarshal([]byte(j.additionalMetadata), additionalMetadata); err != nil {\n\t\treturn nil, errors.Wrap(err, \"error while unmarshalling additional metadata\")\n\t}\n\treturn &SnapshotMetadata{\n\t\tSnapshotSignableMetadata:   metadata,\n\t\tsnapshotAdditionalMetadata: additionalMetadata,\n\t}, nil\n}\n\n// generateSnapshot generates a snapshot. This function should be invoked when commit on the kvledger are paused\n// after committing the last block fully and further the commits should not be resumed till this function finishes\nfunc (l *kvLedger) generateSnapshot() error {\n\tsnapshotsRootDir := l.config.SnapshotsConfig.RootDir\n\tbcInfo, err := l.GetBlockchainInfo()\n\tif err != nil {\n\t\treturn err\n\t}\n\tlastBlockNum := bcInfo.Height - 1\n\tsnapshotTempDir, err := os.MkdirTemp(\n\t\tSnapshotsTempDirPath(snapshotsRootDir),","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/ledger/kvledger/snapshot.go#L65-L101","documentation":"ToMetadata deserializes a snapshot's signable and additional metadata blobs from JSON. This error wraps a json.Unmarshal failure on the additionalMetadata blob (data that is not part of the signed snapshot metadata, e.g. requested app/grpc hashes), indicating the stored snapshot metadata file is corrupt or in an unexpected format.","triggerScenarios":"Calling snapshotMetadataFromProto/ToMetadata on a snapshot whose additional-metadata JSON file (or proto field) is malformed, truncated, empty, or was written by an incompatible format/version.","commonSituations":"Snapshot files manually edited or copied incompletely between nodes; disk corruption; mixing snapshot metadata produced by a different Hyperledger Fabric version where the additional metadata schema changed.","solutions":["Regenerate or re-fetch the snapshot from a trusted peer, since a malformed metadata blob usually means the snapshot is corrupt","Validate the additional-metadata JSON with a linter (jq) to confirm exactly which field fails to parse","Ensure the Fabric version reading the snapshot matches the one that generated it","Check disk/filesystem integrity where the snapshot was stored"],"exampleFix":"// before\nmetadata, err := ToMetadata(j)\n// after\nif !json.Valid([]byte(j.additionalMetadata)) {\n    return nil, errors.New(\"snapshot additional metadata is not valid JSON; regenerate snapshot\")\n}\nmetadata, err := ToMetadata(j)","handlingStrategy":"validation","validationCode":"if !json.Valid([]byte(meta.GetAdditionalMetadata())) {\n    return errors.New(\"snapshot additional metadata is not valid JSON; snapshot is corrupt or from an incompatible version\")\n}","typeGuard":null,"tryCatchPattern":"metadata, err := snapshotMetadataFromProto(protoMeta)\nif err != nil {\n    return fmt.Errorf(\"rejecting snapshot: %w\", err) // fail closed; regenerate snapshot\n}","preventionTips":["Never hand-edit snapshot metadata files","Verify snapshot hashes after copying between nodes","Keep Fabric versions consistent across the network","Store snapshots on reliable storage with checksums"],"tags":["json","unmarshal","snapshot","corruption"],"backgroundTag":"json-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"}