hyperledger/fabric · error

illegal file detected in payload: "%s"

Error message

illegal file detected in payload: "%s"

What it means

This error is thrown by ValidateCodePackage in the Node.js chaincode platform when a tar entry name inside the deployment payload fails the conforming-path regex. The platform scans every header of the packaged .tar.gz and rejects any file whose path does not match the allowed pattern, since arbitrary or absolute paths could escape the src/ layout (path traversal).

Source

Thrown at core/chaincode/platforms/node/platform.go:101

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

	foundPackageJson := false
	for {
		header, err := tr.Next()
		if err != nil {
			// We only get here if there are no more entries to scan
			break
		}

		// --------------------------------------------------------------------------------------
		// Check name for conforming path
		// --------------------------------------------------------------------------------------
		if !re.MatchString(header.Name) {
			return fmt.Errorf("illegal file detected in payload: \"%s\"", header.Name)
		}
		if header.Name == "src/package.json" {
			foundPackageJson = true
		}
		// --------------------------------------------------------------------------------------
		// Check that file mode makes sense
		// --------------------------------------------------------------------------------------
		// Acceptable flags:
		//      ISREG      == 0100000
		//      -rw-rw-rw- == 0666
		//
		// Anything else is suspect in this context and will be rejected
		// --------------------------------------------------------------------------------------
		if header.Mode&^0o100666 != 0 {
			return fmt.Errorf("illegal file mode detected for file %s: %o", header.Name, header.Mode)
		}
	}
	if !foundPackageJson {

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Rebuild the chaincode package so every tar entry uses a relative path under src/ (package.json must be exactly 'src/package.json').
2. Verify no tar entry contains '..' segments or absolute paths (tar -tf package.tar.gz to inspect).
3. Use the platform's own GetDeploymentPayload (the packaging API) instead of manually creating the tarball.
4. Unpack the archive, normalize file names, and re-tar with relative paths (e.g. tar -czf pkg.tar.gz -C <root> .).

Example fix

// before: tar created with absolute paths
tar -czf chaincode.tar.gz /home/user/chaincode/src
// after: relative paths under src/
tar -czf chaincode.tar.gz -C /home/user/chaincode src

const okEntry = (name) => !name.includes('..') && !path.isAbsolute(name) && name.startsWith('src/');
// verify every tar entry before submitting:
// entries.every(e => okEntry(e.name))

function isConformingEntry(name) {
  return typeof name === 'string' && name.startsWith('src/') && !name.includes('..') && !path.isAbsolute(name);
}

When it happens

Trigger: Calling ValidateCodePackage with a code package whose tar archive contains a header.Name that does not match the platform's conforming-path regular expression — e.g. entries with '..' segments, absolute paths, or unexpected prefixes like 'package.json' instead of 'src/package.json'.

Common situations: Hand-crafted chaincode packages built with a different directory layout, packages generated by tools that store absolute paths, packages with symlinks or parent-directory entries, or corrupted/edited .tar.gz payloads.

Related errors

• did not find a code package inside the package
• illegal file detected in payload: "%s"
• illegal file mode detected for file %s: %o
• no package.json found at the root of the chaincode package
• ChaincodeSpec's path cannot be empty

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