hyperledger/fabric · error

did not find any package metadata (missing %s)

Error message

did not find any package metadata (missing %s)

What it means

ParseChaincodePackage requires a metadata member (MetadataFile, i.e. metadata.json) at the top level of the chaincode package archive. If the archive contains a code package but no metadata entry, ccPackageMetadata stays nil and this error is thrown.

Source

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

			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 using `peer lifecycle chaincode package` so metadata.json is emitted at the archive top level
2. Inspect the archive (`tar -tf`) and confirm a top-level metadata.json exists with the exact expected name
3. If building packages programmatically, serialize PackageMetadata {Type, Path, Label} to metadata.json and add it to the tarball before the code package

Example fix

// before
// tar: code.tar.gz only

// after
// tar: metadata.json (contains {"Type":"golang","Path":"./src","Label":"mycc_1.0"}), label, code.tar.gz

entries, _ := listTarTopLevel(pkgBytes)
if !slices.Contains(entries, "metadata.json") {
    return errors.New("chaincode package is missing metadata.json")
}

func hasMetadata(entries []string) bool { return slices.Contains(entries, "metadata.json") }

ccPackage, digest, err := parser.Parse(pkgBytes)
if err != nil {
    if strings.Contains(err.Error(), "did not find any package metadata") {
        return fmt.Errorf("rebuild package with metadata.json: %w", err)
    }
    return err
}

When it happens

Trigger: Calling Parse or PackageID on a tar archive that contains the code payload but is missing the metadata.json top-level file, or where metadata.json failed to parse and was skipped (metadata parse errors also leave ccPackageMetadata nil).

Common situations: Manually assembled packages missing metadata.json; packages built with an incompatible/older tool version; archive corrupted so the metadata entry name does not match exactly.

Related errors

• did not find a code package inside the package
• Error writing %s to tar: %s
• failure opening codepackage gzip stream: %s
• illegal file detected in payload: "%s"
• ChaincodeSpec's path cannot be empty

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