hyperledger/fabric · error · VSCCExecutionFailureError

failed obtaining query executor: %v

Error message

failed obtaining query executor: %v

What it means

validateRWSetAndCollection calls vscc.stateFetcher.FetchState() to get a query executor against the ledger. If that fails, the error is wrapped in a VSCCExecutionFailureError (a transient execution failure, not an endorsement-policy error). Common underlying causes are the ledger/store being unavailable or an internal database error.

Source

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

	var collectionsConfigLedger []byte
	if len(lsccrwset.Writes) == 2 {
		key := privdata.BuildCollectionKVSKey(cdRWSet.Name)
		if lsccrwset.Writes[1].Key != key {
			return policyErr(fmt.Errorf("invalid key for the collection of chaincode %s:%s; expected '%s', received '%s'",
				cdRWSet.Name, cdRWSet.Version, key, lsccrwset.Writes[1].Key))
		}

		collectionsConfigLedger = lsccrwset.Writes[1].Value
	}

	if !bytes.Equal(collectionsConfigArg, collectionsConfigLedger) {
		return policyErr(fmt.Errorf("collection configuration arguments supplied for chaincode %s:%s do not match the configuration in the lscc writeset",
			cdRWSet.Name, cdRWSet.Version))
	}

	channelState, err := vscc.stateFetcher.FetchState()
	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),

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Check the peer logs immediately preceding this error for the underlying query-executor failure and fix the state database (verify CouchDB/LevelDB is running and reachable).
2. Restart the peer once the state store is healthy; blocks will be revalidated.
3. For CouchDB, verify CORE_LEDGER_STATE_COUCHDBCONFIG_* settings and network connectivity from the peer container.
4. If this recurs during startup, ensure ordering/validation services don't race peer ledger initialization.

Example fix

// before: peer cannot reach CouchDB
docker start couchdb  # or fix CORE_LEDGER_STATE_COUCHDBCONFIG_ADDRESS
// after: verify state store availability before starting peer
curl -f http://couchdb:5984/_up && peer node start

// Health-check the state store before submitting deploys
// e.g. for CouchDB:
// curl -f http://couchdb:5984/_up || restart couchdb before invoking lscc

// VSCCExecutionFailureError is transient — retry validation/commit
if _, ok := err.(*commonerrors.VSCCExecutionFailureError); ok {
  // log underlying cause and retry after checking the state database
  logger.Warnf("transient VSCC failure, retrying: %v", err)
  return retryWithBackoff(validateTx)
}

When it happens

Trigger: FetchState() returns an error while validating an lscc deploy with collections — e.g. the peer cannot obtain a query executor from the state provider because the backing state database (LevelDB/CouchDB) is down, misconfigured, or the ledger is being recovered.

Common situations: CouchDB container stopped or unreachable during block validation; peer starting up and ledger state provider not yet ready; disk full or database corruption on the state store.

Related errors

• unable to check whether collection existed earlier for chain
• unexpected end of blockfile
• error opening block file %s
• error seeking block file [%s] to startOffset [%d]
• Could not seek block file [%s] to startOffset [%d]. New posi

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