hyperledger/fabric · error

illegal file name in payload: %s

Error message

illegal file name in payload: %s

What it means

ValidateCodePackage iterates over the tar entries of a chaincode package and checks each archive header name against a regex of allowed characters/paths. If a tar entry name does not conform, this error is returned to reject packages that could contain path traversal or unsafe file names.

Source

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

	gr, err := gzip.NewReader(is)
	if err != nil {
		return fmt.Errorf("failure opening codepackage gzip stream: %s", err)
	}

	re := regexp.MustCompile(`^(src|META-INF)/`)
	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

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Repackage the chaincode with relative, slash-separated paths using tar (no leading '/', no '..').
2. Verify each entry name with the same regex (^[^:\\]+ or project's pattern) before packaging.
3. Build the package via the SDK/peer lifecycle tooling rather than manual tar.
4. Remove entries with Windows drive letters or backslashes; re-create the archive on Linux.

Example fix

// before: tar created on Windows with backslash paths
tar -cf code.tar.gz src\main.go
// after
tar -czf code.tar.gz src/main.go

import ("archive/tar"; "regexp"; "bytes")
func entryNamesOK(tgz []byte) error {
	re := regexp.MustCompile(`^[^:\\]+(/[^:\\]+)*$`)
	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 }
		if !re.MatchString(h.Name) { return fmt.Errorf("bad name: %s", h.Name) }
	}
}

if err := platform.ValidateCodePackage(pkg); err != nil {
	if strings.Contains(err.Error(), "illegal file name in payload") {
		// repackage archive with clean relative paths
	}
}

When it happens

Trigger: Calling ValidateCodePackage with a tar.gz code package containing an entry whose Name fails the re.MatchString check, e.g. names with illegal characters, absolute paths, or '..' segments.

Common situations: Developers hand-crafting chaincode deployment packages, using non-Go tooling (Windows tar, 7-zip) that emits backslash-separated or absolute entry names, or packaging symlinks/odd paths.

Related errors

• illegal file mode in payload: %s
• Error writing %s to tar: %s
• failed to create tar for chaincode
• cannot collect files from empty chaincode path
• invalid chaincode ID

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