hyperledger/fabric · error

illegal file detected in payload: "%s"

Error message

illegal file detected in payload: "%s"

What it means

While iterating the tar entries inside the chaincode package, every entry name must match the allowed regexp (^(/)?src/... or build.gradle/settings.gradle/pom.xml at the root) and must not be a .class file. Any entry violating these rules triggers this error naming the offending file.

Source

Thrown at core/chaincode/platforms/java/platform.go:70

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

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

		// --------------------------------------------------------------------------------------
		// Check name for conforming path
		// --------------------------------------------------------------------------------------
		if !filesToMatch.MatchString(header.Name) || filesToIgnore.MatchString(header.Name) {
			return fmt.Errorf("illegal file detected in payload: \"%s\"", header.Name)
		}

		// --------------------------------------------------------------------------------------
		// 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)
		}
	}
	return nil
}

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Repackage so all sources live under src/ (or META-INF/) plus root build.gradle/settings.gradle/pom.xml
2. Remove .class files from the package (clean the build output before packaging)
3. Rebuild the tar from the project root so entries are correctly prefixed
4. Inspect the package with `tar -tf mypackage.tgz` and remove disallowed entries

Example fix

// before
// tar contains: README.md, src/contract.jar, target/App.class
// after
// tar contains only: src/contract.jar, src/META-INF/MANIFEST.MF, pom.xml

func precheckTarNames(tarPath string) error {
    f, err := os.Open(tarPath); if err != nil { return err }
    defer f.Close()
    gr, err := gzip.NewReader(f); if err != nil { return err }
    tr := tar.NewReader(gr)
    re := regexp.MustCompile(`^(/)?src/((src|META-INF)/.*|(build\.gradle|settings\.gradle|pom\.xml))`)
    bad := regexp.MustCompile(`.*\.class$`)
    for {
        h, err := tr.Next()
        if err == io.EOF { return nil }
        if err != nil { return err }
        if !re.MatchString(h.Name) || bad.MatchString(h.Name) {
            return fmt.Errorf("disallowed entry: %s", h.Name)
        }
    }
}

if err := platform.ValidateCodePackage(code); err != nil {
    var name string
    if m := regexp.MustCompile(`illegal file detected in payload: "(.*)"`).FindStringSubmatch(err.Error()); m != nil {
        name = m[1] // repack excluding this entry
    }
}

When it happens

Trigger: ValidateCodePackage encounters a tar header whose Name does not match the permitted paths (files outside src/, META-INF/, or the three root build files) or whose name ends in .class.

Common situations: Packaging a project with stray files at the tar root (README, IDE config, node_modules-like leftovers); including compiled .class files from a stale build directory; building the tar from the wrong directory so paths lack the src/ prefix.

Related errors

• did not find a code package inside the package
• failure opening codepackage gzip stream: %s
• ChaincodeSpec's path cannot be empty
• failed to create chaincode package: %s
• illegal file detected in payload: "%s"

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