k3s-io/k3s · error

tar file entry %s contained unsupported file type %v

Error message

tar file entry %s contained unsupported file type %v

What it means

Each tar entry is dispatched on its FileInfo mode: regular files, directories, and entries with a Linkname (symlinks and hard links) are handled; anything else falls through to this error. The archive contains a device node, FIFO/named pipe, socket, or another special file type that this extractor refuses to create.

Source

Thrown at pkg/untar/untar.go:123

					// on it anywhere (the gomote push command relies
					// on digests only), so this is a little pointless
					// for now.
					logrus.Printf("error changing modtime: %v (further Chtimes errors suppressed)", err)
					loggedChtimesError = true // once is enough
				}
			}
			nFiles++
		case mode.IsDir():
			if err := os.MkdirAll(abs, 0755); err != nil {
				return err
			}
			madeDir[abs] = true
		case f.Linkname != "":
			if err := os.Symlink(f.Linkname, abs); err != nil {
				return err
			}
		default:
			return fmt.Errorf("tar file entry %s contained unsupported file type %v", f.Name, mode)
		}
	}
	return nil
}

func validRelPath(p string) bool {
	if p == "" || strings.Contains(p, `\`) || strings.HasPrefix(p, "/") || strings.Contains(p, "../") {
		return false
	}
	return true
}

View on GitHub (pinned to 6ba341e396)

Solutions

1. List entry types: tar -tvf bundle.tar and look for type chars other than '-', 'd', 'l' (e.g. 'p', 'c', 'b')
2. Re-create the archive excluding special files, e.g. tar --exclude=/dev -C srcdir -cf bundle.tar .
3. If the special files are genuinely needed, extract them out-of-band with a tool that supports them, and review why they exist

Example fix

# before
tar -cf bundle.tar /opt/app /var/run/app.fifo
# after
tar -C /opt/app -cf bundle.tar .  # files, dirs, symlinks only

func TarballHasOnlySupportedTypes(r io.Reader) error {
	zr, err := zstd.NewReader(r)
	if err != nil {
		return err
	}
	defer zr.Close()
	tr := tar.NewReader(zr)
	for {
		h, err := tr.Next()
		if err == io.EOF {
			return nil
		}
		if err != nil {
			return err
		}
		switch h.Typeflag {
		case tar.TypeReg, tar.TypeDir, tar.TypeSymlink, tar.TypeLink, tar.TypeXHeader, tar.TypeXGlobalHeader, tar.TypeGNULongName, tar.TypeGNULongLink:
		default:
			return fmt.Errorf("unsupported entry %q type %q", h.Name, h.Typeflag)
		}
	}
}

func isSupportedTarType(tf byte) bool {
	switch tf {
	case tar.TypeReg, tar.TypeRegA, tar.TypeDir, tar.TypeSymlink, tar.TypeLink:
		return true
	}
	return false
}

if err := untar.Untar(r, dir); err != nil {
	if strings.Contains(err.Error(), "unsupported file type") {
		// archive contains device nodes/FIFOs: regenerate it without special files
	}
	return err
}

When it happens

Trigger: untar.Untar on an archive including /dev entries (char/block devices), FIFOs created by a build step, or any entry whose mode is not regular/dir and whose Linkname is empty.

Common situations: Tarring a root filesystem or /dev wholesale; container images with device nodes baked in; build artifacts that accidentally include named pipes or sockets.

Related errors

• tar contained invalid name error %q
• error writing to %s: %v
• only wrote %d bytes to %s; expected %d
• error extracting zstd-compressed body: %v
• tar error: %v

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/91b50e30b58a122f. Report an issue: GitHub.