hyperledger/fabric · error

error marshalling ledger metadata

Error message

error marshalling ledger metadata

What it means

In upgradeFormat (run by UpgradeIDStoreFormat/UpgradeDBs), the code marshals a new LedgerMetadata{Status: ACTIVE} proto to write a metadata key for every existing ledger. protoutil.Marshal of this simple in-memory proto essentially only fails on internal proto serialization errors, so this failure signals an environment/library-level problem rather than bad user input; the upgrade transaction is aborted and the error is wrapped with this message.

Source

Thrown at core/ledger/kvledger/kv_ledger_provider.go:603

func (s *idStore) upgradeFormat() error {
	eligible, err := s.checkUpgradeEligibility()
	if err != nil {
		return err
	}
	if !eligible {
		return nil
	}

	logger.Infof("Upgrading ledgerProvider database to the new format %s", dataformat.CurrentFormat)

	batch := &leveldb.Batch{}
	batch.Put(formatKey, []byte(dataformat.CurrentFormat))

	// add new metadata key for each ledger (channel)
	metadata, err := protoutil.Marshal(&msgs.LedgerMetadata{Status: msgs.Status_ACTIVE})
	if err != nil {
		logger.Errorf("Error marshalling ledger metadata: %s", err)
		return errors.Wrapf(err, "error marshalling ledger metadata")
	}
	itr := s.db.GetIterator(genesisBlkKeyPrefix, genesisBlkKeyStop)
	defer itr.Release()
	for itr.Error() == nil && itr.Next() {
		id := ledgerIDFromGenesisBlockKey(itr.Key())
		batch.Put(metadataKey(id), metadata)
	}
	if err = itr.Error(); err != nil {
		logger.Errorf("Error while upgrading idStore format: %s", err)
		return errors.Wrapf(err, "error while upgrading idStore format")
	}

	return s.db.WriteBatch(batch, true)
}

func (s *idStore) createLedgerID(ledgerID string, metadata *msgs.LedgerMetadata) error {
	m, err := s.getLedgerMetadata(ledgerID)
	if err != nil {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Rebuild the upgrade tool/peer against the official Fabric module versions so generated msgs protos and google.golang.org/protobuf are consistent (go mod tidy, clear vendor dir).
2. Retry the upgrade after rebuilding; the input is static so transient failures indicate environment, not data.
3. If it persists, capture the underlying proto error from the peer log ('Error marshalling ledger metadata: %s') and file/check the Fabric issue tracker for your versions.

Example fix

// before: mismatched protobuf deps after custom vendoring
vendor/github.com/golang/protobuf  (v1.3.x)
vendor/google.golang.org/protobuf  (v1.28.x)

// after: align modules and rebuild
go mod tidy
rm -rf vendor && go mod vendor
go build -o peer ./cmd/peer

// Before running the upgrade, verify the protobuf runtime marshals the metadata message
func verifyProtoMarshal() error {
	b, err := protoutil.Marshal(&msgs.LedgerMetadata{Status: msgs.Status_ACTIVE})
	if err != nil {
		return fmt.Errorf("protobuf runtime broken: %w", err)
	}
	if len(b) == 0 {
		return errors.New("unexpected empty marshal output")
	}
	return nil
}

if err := kvledger.UpgradeIDStoreFormat(dbPath); err != nil {
	if strings.Contains(err.Error(), "error marshalling ledger metadata") {
		log.Fatalf("protobuf marshal failed during upgrade; rebuild binaries with aligned protobuf deps: %v", err)
	}
	return err
}

When it happens

Trigger: Calling UpgradeIDStoreFormat (or UpgradeDBs) against a pre-v2.0 idStore when protoutil.Marshal(&msgs.LedgerMetadata{Status: msgs.Status_ACTIVE}) returns an error — e.g. a broken/incorrectly generated protobuf runtime, or reflection/registry failures from a mismatched protobuf dependency version.

Common situations: See trigger scenarios.

Related errors

• error while unmarshalling metadata bytes for ledger [%s]
• panic(err)
• marshal failed: proto: Marshal called with nil
• could not marshal field %s
• unknown collection configuration type

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