hyperledger/fabric · error

illegal file mode detected for file %s: %o

Error message

illegal file mode detected for file %s: %o

What it means

ValidateCodePackage rejects any tar header whose mode has bits outside the allowed mask 0100666 (regular file + rw-rw-rw-). Executable, setuid, device, or directory-style modes are considered suspect in a Node.js chaincode payload, so the platform fails fast with the offending file and its octal mode.

Source

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

		// 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 {
		return fmt.Errorf("no package.json found at the root of the chaincode package")
	}

	return nil
}

// Generates a deployment payload by putting source files in src/$file entries in .tar.gz format
func (p *Platform) GetDeploymentPayload(path string) ([]byte, error) {
	var err error

	// --------------------------------------------------------------------------------------
	// Write out our tar package
	// --------------------------------------------------------------------------------------
	payload := bytes.NewBuffer(nil)
	gw := gzip.NewWriter(payload)

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Normalize file permissions to 0644 (chmod 644 on all packaged files) and re-tar without preserving permissions.
2. Strip the executable bit: chmod -x src/**/* before packaging.
3. Create the tar without --preserve-permissions and without symlinks (replace symlinks with real files).
4. If a file genuinely needs to be executable, move that logic into a script invoked via package.json with normal file mode.

Example fix

// before: files 0755 inside tar
chmod -R 755 src/ && tar -czf pkg.tar.gz src
// after: normalize modes
cd <project-root> && find src -type f -exec chmod 644 {} + && tar -czf pkg.tar.gz src

const allowed = 0o100666;
// before packaging: assert every file's mode satisfies
// (mode & ~allowed) === 0, e.g. (fs.statSync(f).mode & ~allowed) === 0

function hasLegalMode(mode) {
  return (mode & ~0o100666) === 0;
}

When it happens

Trigger: Packaging a chaincode tarball containing files with modes such as 0755 (executable bit set), symlinks, setuid bits, or any mode where header.Mode&^0o100666 != 0 when ValidateCodePackage is called.

Common situations: Files checked out with exec bits on Windows/Unix shares, scripts chmod +x'ed before packaging, tar created with preserve-permissions flags, or archives that include symlinks/directories with unusual modes.

Related errors

• did not find a code package inside the package
• illegal file detected in payload: "%s"
• illegal file detected in payload: "%s"
• 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/805b41da520f7c5d. Report an issue: GitHub.