hyperledger/fabric · error

empty metadata for supplied chaincode

Error message

empty metadata for supplied chaincode

What it means

InstallChaincode first parses the submitted package with PackageParser.Parse. If the parsed package has no Metadata, the file is not a valid lifecycle chaincode install package and this error is thrown. The package tarball lacks the required metadata.json entry.

Source

Thrown at core/chaincode/lifecycle/lifecycle.go:764

		if len(mismatchItems) > 0 {
			mismatches[org] = mismatchItems
		}
	}

	return
}

// InstallChaincode installs a given chaincode to the peer's chaincode store.
// It returns the hash to reference the chaincode by or an error on failure.
func (ef *ExternalFunctions) InstallChaincode(chaincodeInstallPackage []byte) (*chaincode.InstalledChaincode, error) {
	// Let's validate that the chaincodeInstallPackage is at least well formed before writing it
	pkg, err := ef.Resources.PackageParser.Parse(chaincodeInstallPackage)
	if err != nil {
		return nil, errors.WithMessage(err, "could not parse as a chaincode install package")
	}

	if pkg.Metadata == nil {
		return nil, errors.New("empty metadata for supplied chaincode")
	}

	packageID, err := ef.Resources.ChaincodeStore.Save(pkg.Metadata.Label, chaincodeInstallPackage)
	if err != nil {
		return nil, errors.WithMessage(err, "could not save cc install package")
	}

	buildLock, cleanupBuildLocks := ef.getBuildLock(packageID)
	defer cleanupBuildLocks()

	buildLock.Lock()
	defer buildLock.Unlock()

	buildStatus, ok := ef.BuildRegistry.BuildStatus(packageID)
	if ok {
		// another invocation of lifecycle has concurrently
		// installed a chaincode with this package id
		<-buildStatus.Done()

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Repackage with 'peer lifecycle chaincode package mycc.tar.gz --path <src> --lang <lang> --label mycc_1.0'
2. Verify the tarball contains metadata.json (with type/label/path) at its root and is not truncated
3. Use the exact file produced by the package command for install on all peers
4. Check you are not mixing v1.x '.car'/chaincode-spec artifacts with v2.x lifecycle packages

Example fix

// before: installing a raw source archive
peer lifecycle chaincode install chaincode.tar.gz
// error: empty metadata for supplied chaincode
// after: package first, then install
peer lifecycle chaincode package mycc.tar.gz --path ./chaincode --lang golang --label mycc_1.0
peer lifecycle chaincode install mycc.tar.gz

// Before install, verify the package contains metadata.json:
tar -tzf mycc.tar.gz | grep '^metadata.json$' || echo 'invalid lifecycle package'

try {
  lifecycle.InstallChaincode(pkgBytes)
} catch (err) {
  if strings.Contains(err.Error(), "empty metadata for supplied chaincode") {
    // repackage the chaincode before retrying
  }
}

When it happens

Trigger: Calling 'peer lifecycle chaincode install' with a file that is not a packaged chaincode (e.g. a raw tar.gz without metadata.json, a legacy-BCS .car file, or a truncated download).

Common situations: Passing the source archive instead of the peer lifecycle package output; corrupted transfer; using old lifecycle (v1.x) deployment artifacts with the new lifecycle; wrong --path/--lang packaging.

Related errors

• chaincode already successfully installed (package ID '%s')
• query iterator not found
• application config does not exist for channel '%s'
• unknown chaincode '%s' for channel '%s'
• could not find chaincode with package id '%s'

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