hyperledger/fabric · error

error while unmarshalling additional metadata

Error message

error while unmarshalling additional metadata

What it means

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.

Source

Thrown at core/ledger/kvledger/snapshot.go:83

type SnapshotMetadata struct {
	*SnapshotSignableMetadata
	*snapshotAdditionalMetadata
}

type SnapshotMetadataJSONs struct {
	signableMetadata   string
	additionalMetadata string
}

func (j *SnapshotMetadataJSONs) ToMetadata() (*SnapshotMetadata, error) {
	metadata := &SnapshotSignableMetadata{}
	if err := json.Unmarshal([]byte(j.signableMetadata), metadata); err != nil {
		return nil, errors.Wrap(err, "error while unmarshalling signable metadata")
	}

	additionalMetadata := &snapshotAdditionalMetadata{}
	if err := json.Unmarshal([]byte(j.additionalMetadata), additionalMetadata); err != nil {
		return nil, errors.Wrap(err, "error while unmarshalling additional metadata")
	}
	return &SnapshotMetadata{
		SnapshotSignableMetadata:   metadata,
		snapshotAdditionalMetadata: additionalMetadata,
	}, nil
}

// generateSnapshot generates a snapshot. This function should be invoked when commit on the kvledger are paused
// after committing the last block fully and further the commits should not be resumed till this function finishes
func (l *kvLedger) generateSnapshot() error {
	snapshotsRootDir := l.config.SnapshotsConfig.RootDir
	bcInfo, err := l.GetBlockchainInfo()
	if err != nil {
		return err
	}
	lastBlockNum := bcInfo.Height - 1
	snapshotTempDir, err := os.MkdirTemp(
		SnapshotsTempDirPath(snapshotsRootDir),

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Regenerate or re-fetch the snapshot from a trusted peer, since a malformed metadata blob usually means the snapshot is corrupt
2. Validate the additional-metadata JSON with a linter (jq) to confirm exactly which field fails to parse
3. Ensure the Fabric version reading the snapshot matches the one that generated it
4. Check disk/filesystem integrity where the snapshot was stored

Example fix

// before
metadata, err := ToMetadata(j)
// after
if !json.Valid([]byte(j.additionalMetadata)) {
    return nil, errors.New("snapshot additional metadata is not valid JSON; regenerate snapshot")
}
metadata, err := ToMetadata(j)

if !json.Valid([]byte(meta.GetAdditionalMetadata())) {
    return errors.New("snapshot additional metadata is not valid JSON; snapshot is corrupt or from an incompatible version")
}

metadata, err := snapshotMetadataFromProto(protoMeta)
if err != nil {
    return fmt.Errorf("rejecting snapshot: %w", err) // fail closed; regenerate snapshot
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• error unmarshalling json data
• too few arguments
• Failed opening file %s: %v
• config isn't valid
• error while unmarshalling bootstrappingSnapshotInfo

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/686b5d6ab556fbff. Report an issue: GitHub.