hyperledger/fabric · error · VSCCExecutionFailureError

unable to check whether collection existed earlier for chain

Error message

unable to check whether collection existed earlier for chaincode %s:%s: %v

What it means

On lscc UPGRADE with V1_2 validation enabled, VSCC looks up the previous collection config package from ledger state via privdata.RetrieveCollectionConfigPackageFromState. This error is wrapped in a VSCCExecutionFailureError and means the ledger lookup itself failed with something other than NoSuchCollectionError — i.e. an internal/state-access failure, not a missing collection. Unlike policy errors this signals a validation-system execution failure.

Source

Thrown at core/handlers/validation/builtin/v12/validation_logic.go:462

	if ac.V1_2Validation() {
		newCollectionConfigs := newCollectionConfigPackage.GetConfig()
		if err := validateNewCollectionConfigs(newCollectionConfigs); err != nil {
			return policyErr(err)
		}

		if lsccFunc == lscc.UPGRADE {

			collectionCriteria := privdata.CollectionCriteria{Channel: channelName, Namespace: cdRWSet.Name}
			// oldCollectionConfigPackage denotes the existing collection config package in the ledger
			oldCollectionConfigPackage, err := privdata.RetrieveCollectionConfigPackageFromState(collectionCriteria, state)
			if err != nil {
				// fail if we get any error other than NoSuchCollectionError
				// because it means something went wrong while looking up the
				// older collection
				if _, ok := err.(privdata.NoSuchCollectionError); !ok {
					return &commonerrors.VSCCExecutionFailureError{
						Err: fmt.Errorf("unable to check whether collection existed earlier for chaincode %s:%s: %v",
							cdRWSet.Name, cdRWSet.Version, err),
					}
				}
			}

			// oldCollectionConfigPackage denotes the existing collection config package in the ledger
			if oldCollectionConfigPackage != nil {
				oldCollectionConfigs := oldCollectionConfigPackage.GetConfig()
				if err := validateNewCollectionConfigsAgainstOld(newCollectionConfigs, oldCollectionConfigs); err != nil {
					return policyErr(err)
				}

			}
		}
	}

	return nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Inspect peer logs for the underlying error from RetrieveCollectionConfigPackageFromState to identify the state/db failure.
2. Verify ledger/state DB health (LevelDB/CouchDB reachable and not corrupted); run peer db checks or rebuild state from blocks if corrupted.
3. If state is corrupt, resync the peer from genesis or from a snapshot taken from a healthy peer.
4. Retry endorsement/validation after fixing transient DB issues; as a VSCCExecutionFailureError the tx failure is environmental rather than a policy violation.
5. Ensure the prior chaincode was deployed with a compatible fabric version so stored config packages deserialize correctly.

Example fix

// before: ignoring ledger health, re-submitting the upgrade repeatedly
peer chaincode upgrade -C mychannel ... --collections-config cc.json
// after: fix/verify state DB first, then retry
# e.g. check CouchDB is up, then re-run the upgrade

// distinguish policy vs execution failure on the client/peer side
var vsccErr *commonerrors.VSCCExecutionFailureError
if errors.As(err, &vsccErr) {
    // transient/ledger issue: retry after checking state DB health
    retryUpgradeWithBackoff()
} else {
    // policy error: fix the transaction payload, don't retry blindly
}

When it happens

Trigger: During UPGRADE validation on a channel with private data, RetrieveCollectionConfigPackageFromState returns a non-NoSuchCollectionError (e.g. state/db access error, deserialization failure of the stored config package) while checking whether collections existed earlier for chaincode name:version.

Common situations: Corrupted or partially-written private data state in the ledger; LevelDB/CouchDB I/O errors during validation; state listener inconsistency after peer crash or snapshot restore; bugs when the old chaincode was deployed on an incompatible fabric version.

Related errors

• unknown collection configuration type
• error getting private data by block number %d
• failed to commit private data
• error decoding the block number
• error decoding the data hash

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