pulumi/pulumi · error

unexpected file mode %v for %s

Error message

unexpected file mode %v for %s

What it means

The tar header's Mode field (int64) exceeds math.MaxUint32, so it cannot be safely narrowed to an os.FileMode. The extractor rejects the entry rather than truncating the mode bits.

Source

Thrown at sdk/go/common/util/archive/archive.go:94

		if _, err := os.Stat(path); err != nil {
			if err = os.MkdirAll(path, 0o0700); err != nil {
				return fmt.Errorf("extracting dir %s: %w", path, err)
			}
		}
	case tar.TypeReg:
		// Create any directories as needed. Some tools (notably `npm pack`) don't list
		// directories individually, so if a file is in a directory that doesn't exist, we need
		// to create it here.
		dir := filepath.Dir(path)
		if _, err := os.Stat(dir); err != nil {
			if err = os.MkdirAll(dir, 0o0700); err != nil {
				return fmt.Errorf("extracting dir %s: %w", dir, err)
			}
		}

		// Expand files into the target directory.
		if header.Mode > math.MaxUint32 {
			return fmt.Errorf("unexpected file mode %v for %s", header.Mode, header.Name)
		}
		dst, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, os.FileMode(header.Mode))
		if err != nil {
			return fmt.Errorf("opening file %s for extraction: %w", path, err)
		}
		defer contract.IgnoreClose(dst)

		// We're not concerned with potential tarbombs, so disable gosec.
		if _, err = io.Copy(dst, r); err != nil {
			return fmt.Errorf("untarring file %s: %w", path, err)
		}
	case tar.TypeSymlink:
		// Guard against symlinks that point outside the extraction directory.
		target := header.Linkname
		if !filepath.IsAbs(target) {
			//nolint:gosec // The resolved target is checked against the destination directory below.
			target = filepath.Join(filepath.Dir(path), target)
		}

View on GitHub (pinned to 793f7b2e16)

Solutions

1. Re-download the plugin/archive and verify its checksum
2. Recreate the archive with a standard tool (tar/gzip) so mode fields are valid
3. If you produce archives programmatically, clamp/validate header.Mode before writing the tar

Example fix

// before
header.Mode = 0x1FFFFFFFF // > MaxUint32
// after
header.Mode = 0o755 // valid POSIX mode

f, err := os.Open(tgzPath)
if err != nil { return err }
defer f.Close()
sum := sha256.Sum256(readAll(f))
if !bytes.Equal(sum[:], expectedSum[:]) { return fmt.Errorf("archive checksum mismatch; archive may be corrupted") }

if err := extractFile(r, header, dir); err != nil {
	if strings.Contains(err.Error(), "unexpected file mode") {
		return fmt.Errorf("archive %s has a malformed tar header; re-download it", tgzPath)
	}
	return err
}

When it happens

Trigger: Extracting a tar archive containing a regular-file entry whose mode field is > 0xFFFFFFFF — only possible with malformed or crafted tar headers, since standard tools write modes well under 0o7777.

Common situations: Corrupted download of a plugin tarball; hand-crafted or third-party archive with garbage in the mode field; bit-rotted or truncated archive.

Related errors

• unexpected plugin file type %s (%v)
• failed to create tar reader: %w
• path cannot be empty when constructing a path archive
• uri cannot be empty when constructing a URI archive
• unrecognized archive type

AI-assisted analysis of pulumi/pulumi@793f7b2e16 (2026-08-31). Data as JSON: /api/errors/63210b98be383a19. Report an issue: GitHub.