hyperledger/fabric · error

failed to parse collection config

Error message

failed to parse collection config

What it means

When DeployedChaincodes gathers metadata for deployed chaincodes it reads each chaincode's collection configuration from LSCC and parses it with privdata.ParseCollectionConfig. If the stored collection config bytes cannot be unmarshaled/validated, the error is wrapped as 'failed to parse collection config' and the whole metadata query fails.

Source

Thrown at core/cclifecycle/util.go:72

			Policy:  ccInfo.Policy,
		}

		if !filter(instCC) {
			Logger.Debug("Filtered out", instCC)
			continue
		}

		if loadCollections {
			key := privdata.BuildCollectionKVSKey(cc)
			collectionData, err := q.GetState("lscc", key)
			if err != nil {
				Logger.Errorf("Failed querying lscc namespace for %s: %v", key, err)
				return nil, errors.WithStack(err)
			}
			ccp, err := privdata.ParseCollectionConfig(collectionData)
			if err != nil {
				Logger.Errorf("failed to parse collection config, error %s", err.Error())
				return nil, errors.Wrapf(err, "failed to parse collection config")
			}
			instCC.CollectionsConfig = ccp
			Logger.Debug("Retrieved collection config for", cc, "from", key)
		}

		res = append(res, instCC)
	}
	Logger.Debug("Returning", res)
	return res, nil
}

func deployedCCToNameVersion(cc chaincode.Metadata) nameVersion {
	return nameVersion{
		name:    cc.Name,
		version: cc.Version,
	}
}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Read the underlying cause (Log the wrapped error) to see the unmarshal failure detail.
2. Verify the chaincode's collection config in the channel state via `peer chaincode query` / qscc and, if corrupt, redeploy the chaincode with a valid collection configuration.
3. Check for version incompatibility between the peer parsing the config and the node that wrote it (upgrade peers to a consistent version).
4. If a stale/colliding key exists in LSCC, purge it via proper channel admin tooling rather than direct state edits.

Example fix

// before: deploying with a malformed collection spec JSON
peer lifecycle chaincode approveformyorg --collections-config bad.json
// after: validate the collection config file parses
peer lifecycle chaincode approveformyorg --collections-config collections.json # with valid CollectionConfigPackage JSON

// pre-validate collection config file before deployment
var ccp peer.CollectionConfigPackage
if err := json.Unmarshal(cfgJSON, &ccp); err != nil {
    return fmt.Errorf("invalid collections config: %w", err)
}

func isParsableCollectionConfig(raw []byte) bool {
    var ccp common.CollectionConfigPackage
    return proto.Unmarshal(raw, &ccp) == nil
}

mets, err := metadataMgr.Metadata(channelID, ccName)
if err != nil {
    if strings.Contains(err.Error(), "failed to parse collection config") {
        // treat state as corrupt: redeploy chaincode or rebuild state from blocks
    }
}

When it happens

Trigger: Metadata() -> DeployedChaincodes iterating LSCC keys where the collectionData value stored under an LSCC collection config key is not a valid CollectionConfigPackage protobuf.

Common situations: State database corruption or manual edits to LSCC keys; chaincode deployed by a non-standard/older toolchain writing an unexpected format; reading a key that collides with a collection-config naming pattern but holds different data.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed unmarshalling lscc read value into ChaincodeData
• malformed org definition for org: %s
• error encode input
• message of type %s unknown
• error marshaling: proto: Marshal called with nil

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