hyperledger/fabric · error

Upgrading non-existent chaincode %s

Error message

Upgrading non-existent chaincode %s

What it means

During LSCC (lifecycle system chaincode) transaction validation, VSCC checks that a chaincode being upgraded via lscc.UPGRADE already exists in the instantiated-chaincode table read from the ledger. If no ChaincodeData exists on the ledger for the target name, the upgrade is rejected as a policy error. This prevents fabricating an 'upgrade' to deploy new chaincode outside normal lifecycle rules.

Source

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

			if pol == nil {
				return policyErr(fmt.Errorf("no instantiation policy was specified"))
			}
			// FIXME: could we actually pull the cds package from the
			// file system to verify whether the policy that is specified
			// here is the same as the one on disk?
			// PROS: we prevent attacks where the policy is replaced
			// CONS: this would be a point of non-determinism
			err := vscc.checkInstantiationPolicy(chid, env, pol, payl)
			if err != nil {
				return err
			}

		case lscc.UPGRADE:
			/**************************************************************/
			/* security check 1 - cc in the LCCC table of instantiated cc */
			/**************************************************************/
			if !ccExistsOnLedger {
				return policyErr(fmt.Errorf("Upgrading non-existent chaincode %s", cdsArgs.ChaincodeSpec.ChaincodeId.Name))
			}

			/**********************************************************/
			/* security check 2 - existing cc's version was different */
			/**********************************************************/
			if cdLedger.Version == cdsArgs.ChaincodeSpec.ChaincodeId.Version {
				return policyErr(fmt.Errorf("Existing version of the cc on the ledger (%s) should be different from the upgraded one", cdsArgs.ChaincodeSpec.ChaincodeId.Version))
			}

			/****************************************************************************/
			/* security check 3 validation of rwset (and of collections if enabled) */
			/****************************************************************************/
			// Only in v1.2, a collection can be updated during a chaincode upgrade
			if ac.V1_2Validation() {
				// do extra validation for collections
				err := vscc.validateRWSetAndCollection(lsccrwset, cdRWSet, lsccArgs, lsccFunc, ac, chid)
				if err != nil {
					return err

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Instantiate the chaincode first (lscc DEPLOY) before attempting an upgrade
2. Verify the chaincode name matches exactly the one on the ledger (peer chaincode list --installed/instantiated)
3. Confirm you are issuing the upgrade on the correct channel where the chaincode is instantiated

Example fix

// before
peer chaincode upgrade -C mychannel -n wrongname -v 2.0 ...
// after
peer chaincode list -C mychannel   # confirm exact name
peer chaincode upgrade -C mychannel -n mycc -v 2.0 ...

const instantiated = await peer.chaincodeList(channelName);
if (!instantiated.some(cc => cc.name === targetName)) {
  throw new Error(`Chaincode ${targetName} is not instantiated; instantiate before upgrade`);
}

try {
  await contract.submitTransaction('upgrade', ...);
} catch (e) {
  if (String(e).includes('Upgrading non-existent chaincode')) {
    // fall back to instantiate flow
  }
}

When it happens

Trigger: Submitting an lscc transaction with function UPGRADE for a chaincode name that has never been instantiated (or was fully purged), on channels using the v1.2 validation logic.

Common situations: Typing the wrong chaincode name in the upgrade command; upgrading on a different channel than the one where the chaincode was instantiated; attempting an upgrade after the chaincode was deleted or the ledger was resynced/reset.

Related errors

• invalid collection configuration supplied for chaincode %s:%
• malformed chaincode invocation spec
• Wrong number of arguments for invocation lscc(%s): expected
• Wrong number of arguments for invocation lscc(%s): received
• Existing version of the cc on the ledger (%s) should be diff

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