hyperledger/fabric · error

illegal file mode in payload: %s

Error message

illegal file mode in payload: %s

What it means

During tar validation, ValidateCodePackage checks each entry's file mode and allows only regular files and directories (mode bits within 0o777 or ModeDir). Entries with setuid/setgid bits, symlinks, devices, or other special file types trigger this error.

Source

Thrown at core/chaincode/platforms/golang/platform.go:102

	tr := tar.NewReader(gr)
	for {
		header, err := tr.Next()
		if err == io.EOF {
			break
		}
		if err != nil {
			return err
		}

		// maintain check for conforming paths for validation
		if !re.MatchString(header.Name) {
			return fmt.Errorf("illegal file name in payload: %s", header.Name)
		}

		// only files and directories; no links or special files
		mode := header.FileInfo().Mode()
		if mode&^(os.ModeDir|0o777) != 0 {
			return fmt.Errorf("illegal file mode in payload: %s", header.Name)
		}
	}

	return nil
}

// Directory constant copied from tar package.
const c_ISDIR = 0o40000

// Default compression to use for production. Test packages disable compression.
var gzipCompressionLevel = gzip.DefaultCompression

// GetDeploymentPayload creates a gzip compressed tape archive that contains the
// required assets to build and run go chaincode.
//
// NOTE: this is only used at the _client_ side by the peer CLI.
func (p *Platform) GetDeploymentPayload(codepath string) ([]byte, error) {
	codeDescriptor, err := DescribeCode(codepath)

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Recreate the tar with only regular files and directories (tar --format=ustar without symlinks).
2. Replace symlinks with real copies of the files before packaging.
3. Normalize permissions to standard values (e.g. chmod 755/644) before archiving.

Example fix

// before: symlink included
tar -czf code.tar.gz src link-to-src
// after: dereference symlinks
tar -czhf code.tar.gz src

func entryModesOK(tgz []byte) error {
	gr, _ := gzip.NewReader(bytes.NewReader(tgz))
	tr := tar.NewReader(gr)
	for {
		h, err := tr.Next()
		if err == io.EOF { return nil }
		if err != nil { return err }
		m := h.FileInfo().Mode()
		if m&^(os.ModeDir|0o777) != 0 { return fmt.Errorf("bad mode: %s", h.Name) }
	}
}

if err := platform.ValidateCodePackage(pkg); err != nil {
	if strings.Contains(err.Error(), "illegal file mode in payload") {
		// repackage with symlinks dereferenced (tar -h) and plain permissions
	}
}

When it happens

Trigger: Calling ValidateCodePackage on a package whose tar contains a symlink, hardlink, fifo, socket, or device entry, or permission bits outside 0o777 (e.g. setuid files).

Common situations: Packaging symlinks from node_modules-like trees, archiving with flags preserving special files, or files with setgid group-exec bits from shared build dirs.

Related errors

• illegal file name in payload: %s
• Error writing %s to tar: %s
• failed to create tar for chaincode
• First message needs to be a register
• TLS is active but chaincode %s didn't send certificate

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