the following existing collections are missing in the new co

Error message

the following existing collections are missing in the new collection configuration package: %v

What it means

During a chaincode upgrade, checkForMissingCollections verifies that every collection defined in the existing (old) collection config is still present in the new package. Private data collections cannot be removed via upgrade, so if any old collection name is absent from the new config, the transaction is rejected with the list of missing collection names.

Source

Thrown at core/handlers/validation/builtin/v13/lscc_validation_logic.go:145

	// number of new collections are allowed.
	for _, oldCollectionConfig := range oldCollectionConfigs {

		oldCollection := oldCollectionConfig.GetStaticCollectionConfig()
		// It cannot be nil
		if oldCollection == nil {
			return policyErr(fmt.Errorf("unknown collection configuration type"))
		}

		// All old collection must exist in the new collection config package
		oldCollectionName := oldCollection.GetName()
		_, ok := newCollectionsMap[oldCollectionName]
		if !ok {
			missingCollections = append(missingCollections, oldCollectionName)
		}
	}

	if len(missingCollections) > 0 {
		return policyErr(fmt.Errorf("the following existing collections are missing in the new collection configuration package: %v",
			missingCollections))
	}

	return nil
}

func checkForModifiedCollectionsBTL(newCollectionsMap map[string]*pb.StaticCollectionConfig, oldCollectionConfigs []*pb.CollectionConfig,
) error {
	var modifiedCollectionsBTL []string

	// In the new collection config package, ensure that the block to live value is not
	// modified for the existing collections.
	for _, oldCollectionConfig := range oldCollectionConfigs {

		oldCollection := oldCollectionConfig.GetStaticCollectionConfig()
		// It cannot be nil
		if oldCollection == nil {
			return policyErr(fmt.Errorf("unknown collection configuration type"))

View on GitHub (pinned to 2736b63f8f)

Solutions

Add all existing collection definitions back into the new collections config, unchanged where possible
To stop writing new data to a collection, keep the definition but you cannot remove it; plan archival/retention via BlockToLive instead of deleting
Generate the new config by loading the old collection config and appending new collections rather than authoring from scratch

Example fix

// before (new config for upgrade from coll1+coll2)
[{"name": "coll1"}]
// after
[{"name": "coll1"}, {"name": "coll2"}]

Defensive patterns

Strategy: validation

Validate before calling

function validateUpgradeCollections(oldConfigs, newConfigs) {
  const newNames = new Set(newConfigs.map(c => c.name));
  const missing = oldConfigs.filter(c => !newNames.has(c.name)).map(c => c.name);
  if (missing.length) {
    throw new Error(`existing collections missing from new config: ${missing.join(', ')}`);
  }
}

Type guard

function containsAllOldCollections(oldConfigs, newConfigs) {
  const names = new Set(newConfigs.map(c => c.name));
  return oldConfigs.every(c => names.has(c.name));
}

Try / catch

try {
  await contract.submitTransaction('UpgradeChaincode', ...args);
} catch (err) {
  if (String(err).includes('existing collections are missing')) {
    // parse listed names, merge them back into the new config, resubmit
  }
  throw err;
}

Prevention

Always derive upgrade configs from the previously committed collection definitions
Remember collections cannot be deleted via upgrade — plan retention with blockToLive instead
Diff old vs new collection name sets in CI before submitting upgrades

When it happens

Trigger: Submitting an upgrade with a new collections-config that omits one or more collections that existed in the previous definition, e.g. old config had coll1 and coll2, new config only lists coll1.

Common situations: Creating a fresh collections JSON for the upgrade instead of extending the original; intentionally trying to 'delete' a collection via upgrade (unsupported); copy/paste truncation of the config file.

Related errors

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