existing collection [%s] missing in the proposed collection

Error message

existing collection [%s] missing in the proposed collection configuration

What it means

On chaincode upgrade, every previously committed collection must appear by name in the proposed collection config; new collections may be added but existing ones may not be dropped. This error names the committed collection that is absent from the proposal.

Source

Thrown at core/chaincode/lifecycle/scc.go:948

	}

	proposedCollsMap := map[string]*pb.StaticCollectionConfig{}
	for _, c := range proposedCollConfs {
		proposedCollsMap[c.Name] = c
	}

	// In the new collection config package, ensure that there is one entry per old collection. Any
	// number of new collections are allowed.
	for _, committedCollConfig := range committedCollConfPkg.Config {
		committedColl := committedCollConfig.GetStaticCollectionConfig()
		// It cannot be nil
		if committedColl == nil {
			return errors.Errorf("unknown collection configuration type")
		}

		newCollection, ok := proposedCollsMap[committedColl.Name]
		if !ok {
			return errors.Errorf("existing collection [%s] missing in the proposed collection configuration", committedColl.Name)
		}

		if newCollection.BlockToLive != committedColl.BlockToLive {
			return errors.Errorf("the BlockToLive in an existing collection [%s] modified. Existing value [%d]", committedColl.Name, committedColl.BlockToLive)
		}
	}
	return nil
}

func (i *Invocation) createOpaqueStates() ([]OpaqueState, error) {
	if i.ApplicationConfig == nil {
		return nil, errors.Errorf("no application config for channel '%s'", i.Stub.GetChannelID())
	}
	orgs := i.ApplicationConfig.Organizations()
	opaqueStates := make([]OpaqueState, 0, len(orgs))
	for _, org := range orgs {
		opaqueStates = append(opaqueStates, &ChaincodePrivateLedgerShim{
			Collection: implicitcollection.NameForOrg(org.MSPID()),

View on GitHub (pinned to 2736b63f8f)

Solutions

Include every existing collection (same name) in the new collection config, preserving BlockToLive.
Keep names identical — collections cannot be renamed or deleted across upgrades.
Fetch the committed collection config first and merge new collections into it rather than writing a fresh list.
Verify each entry's BlockToLive matches the committed value, which is also immutable.

Example fix

// before: only new collection in upgrade JSON
[{"name":"newcoll", ...}]
// after: old collection retained + new one added
[{"name":"oldcoll", "block_to_live": 0, ...}, {"name":"newcoll", ...}]

Defensive patterns

Strategy: validation

Validate before calling

committedNames := map[string]bool{}
for _, c := range committedPkg.Config {
  committedNames[c.GetStaticCollectionConfig().Name] = true
}
proposedNames := map[string]bool{}
for _, c := range proposed {
  proposedNames[c.Name] = true
}
for name := range committedNames {
  if !proposedNames[name] {
    return fmt.Errorf("collection %s must be retained in upgrade", name)
  }
}

Type guard

func allCommittedRetained(committed, proposed []string) bool {
  p := map[string]bool{}
  for _, n := range proposed { p[n] = true }
  for _, n := range committed { if !p[n] { return false } }
  return true
}

Try / catch

if err := commit(...); err != nil {
  if strings.Contains(err.Error(), "missing in the proposed collection configuration") {
    // add the named existing collection back into the config and resubmit
  }
  return err
}

Prevention

Merge new collections into the committed set; never author a fresh list on upgrade.
Never rename or remove existing collections — fabric forbids both.
Preserve BlockToLive values exactly as committed.
Diff proposed vs committed collection names before every upgrade.

When it happens

Trigger: Approving/committing an upgraded chaincode definition whose collection config omits one or more collections present in the committed definition (matched by collection Name).

Common situations: Renaming a collection (fabric does not allow it); trimming 'unused' collections during an upgrade; collection config rebuilt from a partial template.

Related errors

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