hyperledger/fabric · error

plugin with name %s wasn't found

Error message

plugin with name %s wasn't found

What it means

The plugin validator looks up a validation (VSCC) plugin factory by the name in the chaincode's validation parameter. No registered plugin factory matches that name, so validation cannot proceed and the transaction/channel validation fails.

Source

Thrown at core/committer/txvalidator/v14/plugin_validator.go:127

	plugin, err := pv.getOrCreatePlugin(ctx)
	if err != nil {
		return &validation.ExecutionFailureError{
			Reason: fmt.Sprintf("plugin with name %s couldn't be used: %v", ctx.VSCCName, err),
		}
	}
	err = plugin.Validate(ctx.Block, ctx.Namespace, ctx.Seq, 0, vp.SerializedPolicy(ctx.Policy))
	validityStatus := "valid"
	if err != nil {
		validityStatus = fmt.Sprintf("invalid: %v", err)
	}
	logger.Debug("Transaction", ctx.TxID, "appears to be", validityStatus)
	return err
}

func (pv *PluginValidator) getOrCreatePlugin(ctx *Context) (validation.Plugin, error) {
	pluginFactory := pv.FactoryByName(vp.Name(ctx.VSCCName))
	if pluginFactory == nil {
		return nil, errors.Errorf("plugin with name %s wasn't found", ctx.VSCCName)
	}

	pluginsByChannel := pv.getOrCreatePluginChannelMapping(vp.Name(ctx.VSCCName), pluginFactory)
	return pluginsByChannel.createPluginIfAbsent(ctx.Channel)
}

func (pv *PluginValidator) getOrCreatePluginChannelMapping(plugin vp.Name, pf validation.PluginFactory) *pluginsByChannel {
	pv.Lock()
	defer pv.Unlock()
	endorserChannelMapping, exists := pv.pluginChannelMapping[plugin]
	if !exists {
		endorserChannelMapping = &pluginsByChannel{
			pluginFactory:    pf,
			channels2Plugins: make(map[string]validation.Plugin),
			pv:               pv,
		}
		pv.pluginChannelMapping[plugin] = endorserChannelMapping
	}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Ensure the validation plugin is registered in core.yaml under handlers: validators with a matching name
2. Verify the VSCC name recorded in the channel config / chaincode data is correct (usually "vscc")
3. Rebuild the peer including the custom plugin library and restart
4. Align peer Fabric version with the one that created the channel data

Example fix

// before
// core.yaml: handlers: validators: (plugin missing)
// after
handlers:
  validators:
    - name: mycustomvscc
      library: /etc/hyperledger/fabric/plugins/mycustomvscc.so

// peer config check before starting validation work
// read core.yaml handlers.validators and confirm the VSCC name is registered
if !registeredValidators.Contains(vsccName) { return fmt.Errorf("validator %s not configured", vsccName) }

func isKnownVSCC(name string) bool { return name == "vscc" || registeredCustomValidators[name] }

if _, err := pv.getOrCreatePlugin(ctx); err != nil && strings.Contains(err.Error(), "wasn't found") {
    // fix core.yaml handlers or correct the VSCC name in channel config
}

When it happens

Trigger: getOrCreatePlugin is called with ctx.VSCCName whose vp.Name has no entry in the peer's plugin registry — the VSCC name in the channel's chaincode (e.g., after upgrade/ manual config) isn't one of "vscc" or a registered custom plugin name.

Common situations: Custom validation plugin not configured in core.yaml handlers.validators; typo in the VSCC name in the ledger's validation parameter; channel created/updated on a newer Fabric version using a plugin name the peer doesn't know; peer started without the plugin built-in.

Related errors

• failed initializing plugin
• plugin with name %s wasn't found
• number of retries must be zero or greater
• fileSuffix illegal, cannot be empty
• fileSuffix [%s] illegal, cannot contain os path separator

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