What causes "tar entry %s is not a regular file, type %v" in hyperledger/fabric?

Rebuild the tar so the target entry is a regular file (tar -czf out.tgz -C pkgdir metadata.json code.tar).

tar entry %s is not a regular file, type %v

Error message

tar entry %s is not a regular file, type %v

What it means

When scanning the package tar for the requested entry (e.g. metadata.json or code.tar), the code found a matching header.Name but its Typeflag is not tar.TypeReg. The library only supports regular files inside chaincode packages, so directories, symlinks, or special files are rejected with this Errorf (not wrapped).

Source

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

	tarReader := tar.NewReader(gzReader)

	for {
		header, err := tarReader.Next()
		if err == io.EOF {
			break
		}

		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)

View on GitHub (pinned to 2736b63f8f)

Solutions

Rebuild the tar so the target entry is a regular file (tar -czf out.tgz -C pkgdir metadata.json code.tar).
Remove directory/symlink entries: inspect with tar -tvzf and recreate from files only.
Replace symlinks with real file copies before packaging.
Use standard fabric packaging commands instead of manual tar construction.

Example fix

// before: includes directory entries and symlinks
tar -czf mycc.tgz pkgdir/
// after: only regular files at top level
cd pkgdir && tar -czf ../mycc.tgz metadata.json code.tar

Defensive patterns

Strategy: validation

Validate before calling

out, err := exec.Command("tar", "-tvzf", pkgPath).Output()
if err != nil { return err }
for _, line := range strings.Split(string(out), "\n") {
	if strings.TrimSpace(line) != "" && !strings.HasPrefix(line, "-") {
		return fmt.Errorf("non-regular entry in %s: %s", pkgPath, line)
	}
}

Try / catch

if _, err := p.Metadata(pkgPath); err != nil {
	if strings.Contains(err.Error(), "is not a regular file") {
		return fmt.Errorf("repackage %s: tar contains non-file entries", pkgPath)
	}
	return err
}

Prevention

Build tars from files, not directories (avoid './' entries).
Replace symlinks with real copies before packaging.
Inspect 'tar -tvzf' output: first column must be '-' for every entry.
Use canonical fabric packaging tooling.

When it happens

Trigger: Calling Metadata(), MetadataBytes(), or Code() where the tar entry matching the requested name is a directory entry, symlink, hardlink, or device node rather than a regular file.

Common situations: Hand-built tars that include directory entries (tar -czf out.tgz dir/ instead of the files), tars created with symlinked metadata.json, or tooling that repacks packages preserving links.

Related errors

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