{"record":{"id":"00bb1c29af06656e","repo":"hyperledger/fabric","slug":"error-while-unmarshalling-signable-metadata","errorCode":null,"errorMessage":"error while unmarshalling signable metadata","messagePattern":"error while unmarshalling signable metadata","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/ledger/kvledger/snapshot.go","lineNumber":78,"sourceCode":"\nfunc (m *snapshotAdditionalMetadata) ToJSON() ([]byte, error) {\n\treturn json.MarshalIndent(m, \"\", jsonFileIndent)\n}\n\ntype 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 {","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/hyperledger/fabric/blob/2736b63f8fd5932511d56fe68b7039d15977f7f6/core/ledger/kvledger/snapshot.go#L60-L96","documentation":"SnapshotMetadataJSONs.ToMetadata decodes the signable portion of a snapshot metadata file (snapshot_signable_metadata.json) via json.Unmarshal into SnapshotSignableMetadata. If the JSON is malformed, empty, or missing expected fields/types, the operation fails wrapped with this message. It indicates a corrupt or hand-edited snapshot metadata file.","triggerScenarios":"Loading a snapshot's metadata (snapshotMetadataFromMetaFile) when the signable metadata JSON string cannot be parsed — e.g. during 'peer node channel join' from a snapshot or when reconstructing snapshot metadata.","commonSituations":"Truncated or corrupted snapshot files during transfer (incomplete scp/rsync); manual editing of snapshot metadata; generating snapshots with an incompatible Fabric version and consuming them with another; wrong file passed as the snapshot metadata.","solutions":["Validate the JSON files inside the snapshot directory (snapshot_signable_metadata.json parses via jq) and regenerate the snapshot if malformed.","Re-transfer or re-generate the snapshot; a truncated copy is the most common cause.","Ensure the snapshot was created by a compatible Fabric version (v2.x snapshot feature) and is not hand-modified.","If the source is reproducible, take a new snapshot from a healthy peer and retry the channel join."],"exampleFix":"// before: hand-edited metadata\n{\"lastBlockNumber\": \"not-a-number\"}   // json: cannot unmarshal string into Go struct field ... of type uint64\n// after: use the metadata exactly as produced by the peer, verify with:\njq . snapshot_signable_metadata.json","handlingStrategy":"validation","validationCode":"// validate snapshot metadata before consuming it\nfunc validateSnapshotMetadata(dir string) error {\n\tfor _, f := range []string{\"snapshot_signable_metadata.json\", \"snapshot_additional_metadata.json\"} {\n\t\tdata, err := os.ReadFile(filepath.Join(dir, f))\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"missing snapshot metadata %s: %w\", f, err)\n\t\t}\n\t\tvar v map[string]interface{}\n\t\tif err := json.Unmarshal(data, &v); err != nil {\n\t\t\treturn fmt.Errorf(\"invalid JSON in %s: %w\", f, err)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"md, err := jsons.ToMetadata()\nif err != nil {\n\tif strings.Contains(err.Error(), \"error while unmarshalling signable metadata\") {\n\t\treturn nil, fmt.Errorf(\"snapshot metadata corrupt: regenerate or re-transfer the snapshot: %w\", err)\n\t}\n\treturn nil, err\n}","preventionTips":["Never hand-edit files inside a snapshot directory","Verify snapshot transfers with checksums (sha256) before use","Use jq or json.Unmarshal validation on snapshot metadata before joining","Create and consume snapshots with the same compatible Fabric version"],"tags":["hyperledger-fabric","json-unmarshal","snapshot","data-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"}