hyperledger/fabric · error

did not find a code package inside the package

Error message

did not find a code package inside the package

What it means

ParseChaincodePackage iterates over the entries of a chaincode package tarball. When it finishes and never encountered a file other than the metadata file / label file (i.e. no actual code payload entry), it throws this error because the archive is not a valid chaincode package — it lacks the code package member.

Source

Thrown at core/chaincode/persistence/chaincode_package.go:327

		switch header.Name {

		case MetadataFile:
			ccPackageMetadata = &ChaincodePackageMetadata{}
			err := json.Unmarshal(fileBytes, ccPackageMetadata)
			if err != nil {
				return ccPackageMetadata, nil, errors.Wrapf(err, "could not unmarshal %s as json", MetadataFile)
			}

		case CodePackageFile:
			codePackage = fileBytes
		default:
			logger.Warningf("Encountered unexpected file '%s' in top level of chaincode package", header.Name)
		}
	}

	if codePackage == nil {
		return ccPackageMetadata, nil, errors.Errorf("did not find a code package inside the package")
	}

	if ccPackageMetadata == nil {
		return ccPackageMetadata, nil, errors.Errorf("did not find any package metadata (missing %s)", MetadataFile)
	}

	if err := ValidateLabel(ccPackageMetadata.Label); err != nil {
		return ccPackageMetadata, nil, err
	}

	return ccPackageMetadata, codePackage, nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Repackage the chaincode with `peer lifecycle chaincode package` (or package.ChaincodePackage) so the archive contains the code payload alongside metadata.json and label
2. Verify the archive contents (e.g. `tar -tf <pkg>.tgz`) include a code package entry, not only metadata.json/label
3. Re-download or re-export the package if it was truncated in transit and confirm its checksum against the source

Example fix

// before: archive has only metadata
// tar: metadata.json, label

// after: build with the tool so the payload is included
peer lifecycle chaincode package mycc.tar.gz --path ./src --lang golang --label mycc_1.0

entries, err := listTarTopLevel(pkgBytes)
if err != nil { return err }
hasMeta, hasPayload := false, false
for _, e := range entries {
    if e == "metadata.json" { hasMeta = true } else { hasPayload = true }
}
if !hasMeta || !hasPayload { return errors.New("package missing metadata.json or code payload") }

func hasCodePackage(entries []string) bool {
    for _, e := range entries {
        if e != "metadata.json" && e != "label" { return true }
    }
    return false
}

When it happens

Trigger: Calling Parse or PackageID on a tar archive whose top-level entries contain only MetadataFile (metadata.json) and LabelFile (label) but no code package file; or an archive where the payload entry was pruned/corrupted.

Common situations: Hand-crafting a chaincode package with a script that writes only metadata; a truncated tarball produced by a failed install; uploading the wrong archive (e.g. just a metadata descriptor) to `peer lifecycle chaincode install`.

Related errors

• illegal file detected in payload: "%s"
• illegal file detected in payload: "%s"
• illegal file mode detected for file %s: %o
• no package.json found at the root of the chaincode package
• ChaincodeSpec's path cannot be empty

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