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

What it means

When deploying a chaincode with collections, VSCC checks whether the collection already existed earlier via the state's CheckCollectionIsPresentInPreviousExpFile. Any error other than privdata.NoSuchCollectionError is wrapped in a VSCCExecutionFailureError with this message, meaning the lookup of the older collection configuration itself failed (as opposed to the collection simply existing).

Source

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

	if err != nil {
		return &commonerrors.VSCCExecutionFailureError{Err: fmt.Errorf("failed obtaining query executor: %v", err)}
	}
	defer channelState.Done()

	state := &state{channelState}

	// The following condition check added in v1.1 may not be needed as it is not possible to have the chaincodeName~collection key in
	// the lscc namespace before a chaincode deploy. To avoid forks in v1.2, the following condition is retained.
	if lsccFunc == lscc.DEPLOY {
		colCriteria := privdata.CollectionCriteria{Channel: channelName, Namespace: cdRWSet.Name}
		ccp, err := privdata.RetrieveCollectionConfigPackageFromState(colCriteria, 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",
						cdRWSet.Name, cdRWSet.Version),
				}
			}
		}
		if ccp != nil {
			return policyErr(fmt.Errorf("collection data should not exist for chaincode %s:%s", cdRWSet.Name, cdRWSet.Version))
		}
	}

	// TODO: Once the new chaincode lifecycle is available (FAB-8724), the following validation
	// and other validation performed in ValidateLSCCInvocation can be moved to LSCC itself.
	newCollectionConfigPackage := &pb.CollectionConfigPackage{}

	if collectionsConfigArg != nil {
		err := proto.Unmarshal(collectionsConfigArg, newCollectionConfigPackage)
		if err != nil {
			return policyErr(fmt.Errorf("invalid collection configuration supplied for chaincode %s:%s",
				cdRWSet.Name, cdRWSet.Version))

View on GitHub (pinned to 2736b63f8f)

Solutions

Inspect peer logs for the underlying store error from CheckCollectionIsPresentInPreviousExpFile and fix the state database.
Verify ledger integrity; if state data is corrupted, restore the peer from a known-good snapshot or resync from genesis/orderer.
Retry the transaction after the state store is healthy — VSCCExecutionFailureError is treated as transient, not a policy rejection.
Ensure consistent Fabric versions between peers so collection state lookups use the same key schema.

Example fix

// before: corrupted state leads to lookup failure
peer node start  # validation fails with VSCCExecutionFailureError
// after: restore state store and restart
peer node stop && rm -rf /var/hyperledger/production/ledgersData/stateLeveldb && peer node start  # resync from orderer

Defensive patterns

Strategy: try-catch

Try / catch

// Distinguish transient lookup failures from NoSuchCollectionError in custom validators
if err := checkCollectionIsPresentInPreviousExpFile(...); err != nil {
  if _, ok := err.(privdata.NoSuchCollectionError); !ok {
    // wrap as VSCCExecutionFailureError — transient, may be retried
    return &commonerrors.VSCCExecutionFailureError{Err: fmt.Errorf("unable to check whether collection existed earlier: %v", err)}
  }
}

Prevention

Keep ledger state stores healthy; corruption in state data triggers this lookup failure
Restore peers from known-good snapshots after crashes instead of running with partially-written state
Keep peer Fabric versions uniform so previous-collection lookups use the same key schema
Monitor for repeated VSCCExecutionFailureError which signals persistent store problems

When it happens

Trigger: CheckCollectionIsPresentInPreviousExpFile returns a non-NoSuchCollectionError while validating an lscc deploy — e.g. corrupted or inaccessible experimental/collections state data in the ledger, an internal store error reading the '~collection' keys, or a query executor problem during the previous-config lookup.

Common situations: Ledger state corrupted after a crash or failed migration; custom/experimental collection persistence data damaged; database-level failures (CouchDB errors, bad state keys) surfacing during validation of an upgrade transaction.

Related errors

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