hyperledger/fabric · error

did not find file '%s' in package

Error message

did not find file '%s' in package

What it means

After iterating every entry of the package tar without finding one named exactly 'name', the File helper returns this error. The gzip/tar layers are fine; the requested file simply is not present in the archive. Callers use this for metadata.json and code.tar, so a package missing either will surface this.

Source

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

		if err != nil {
			return nil, errors.Wrapf(err, "error inspecting next tar header")
		}

		if header.Name != name {
			continue
		}

		if header.Typeflag != tar.TypeReg {
			return nil, errors.Errorf("tar entry %s is not a regular file, type %v", header.Name, header.Typeflag)
		}

		return &TarFileStream{
			TarFile:    tarReader,
			FileStream: file,
		}, nil
	}

	return nil, errors.Errorf("did not find file '%s' in package", name)
}

type TarFileStream struct {
	TarFile    io.Reader
	FileStream io.Closer
}

func (tfs *TarFileStream) Read(p []byte) (int, error) {
	return tfs.TarFile.Read(p)
}

func (tfs *TarFileStream) Close() error {
	return tfs.FileStream.Close()
}

// ChaincodePackage represents the un-tar-ed format of the chaincode package.
type ChaincodePackage struct {
	Metadata    *ChaincodePackageMetadata

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Check the archive contents: tar -tzvf <package> and confirm 'metadata.json' / 'code.tar' exist with exact names.
2. Repackage with 'peer lifecycle chaincode package' to get canonical entry names.
3. Rename entries to the expected MetadataFile/CodePackageFile names and rebuild the tar.
4. Ensure you packaged at the correct directory level so files land at tar root, not nested in subfolders.

Example fix

// before: nested entries, not found at tar root
tar -czf mycc.tgz ./pkg/*   // entries named pkg/metadata.json
// after: entries at root
cd pkg && tar -czf ../mycc.tgz metadata.json code.tar

names := map[string]bool{}
if out, err := exec.Command("tar", "-tzf", pkgPath).Output(); err == nil {
	for _, n := range strings.Fields(string(out)) { names[filepath.Base(n)] = true }
}
if !names["metadata.json"] || !names["code.tar"] {
	return fmt.Errorf("package %s missing metadata.json or code.tar", pkgPath)
}

meta, err := p.Metadata(pkgPath)
if err != nil {
	if strings.Contains(err.Error(), "did not find file") {
		return fmt.Errorf("%s is missing required entries; repackage with peer lifecycle chaincode package", pkgPath)
	}
	return err
}

When it happens

Trigger: Metadata() or MetadataBytes() when the tar has no 'metadata.json' entry; Code() when there is no 'code.tar' entry — e.g. packages built with different entry names or missing components.

Common situations: Manual packaging that named files differently (META-INF/meta.json, chaincode.tar), packages produced by mismatched fabric versions, or archives where an antivirus/cleanup step stripped files.

Related errors

• error inspecting next tar header
• tar entry %s is not a regular file, type %v
• could not read %s from tar
• invalid deployment spec
• error reading as gzip stream

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