What causes "failed to write tar header: %w" in slimtoolkit/slim?

Rename offending files to use plain ASCII, tar-safe names.

failed to write tar header: %w

Error message

failed to write tar header: %w

What it means

After computing the tar header for a walked file, tw.WriteHeader failed on the in-memory tar writer. Since the writer wraps a bytes.Buffer, this indicates a malformed header — e.g. a Name that cannot be represented in tar (invalid characters, too long without PAX support) or a mode/typeflag inconsistency.

Source

Thrown at pkg/imagebuilder/internalbuilder/engine.go:308

		hdr := &tar.Header{
			Name: path.Join(layerBasePath, filepath.ToSlash(rel)),
			Mode: int64(info.Mode()),
		}

		if !info.IsDir() {
			hdr.Size = info.Size()
		}

		if info.Mode().IsDir() {
			hdr.Typeflag = tar.TypeDir
		} else if info.Mode().IsRegular() {
			hdr.Typeflag = tar.TypeReg
		} else {
			return fmt.Errorf("not implemented archiving file type %s (%s)", info.Mode(), rel)
		}

		if err := tw.WriteHeader(hdr); err != nil {
			return fmt.Errorf("failed to write tar header: %w", err)
		}
		if !info.IsDir() {
			f, err := os.Open(fp)
			if err != nil {
				return err
			}
			if _, err := io.Copy(tw, f); err != nil {
				return fmt.Errorf("failed to read file into the tar: %w", err)
			}
			f.Close()
		}
		return nil
	})

	if err != nil {
		return nil, fmt.Errorf("failed to scan files: %w", err)
	}
	if err := tw.Close(); err != nil {

View on GitHub (pinned to 81940d17fa)

Solutions

Rename offending files to use plain ASCII, tar-safe names.
Sanitize hdr.Name (strip invalid characters) before WriteHeader.
Inspect the wrapped error (%w) to identify the exact header field that was rejected.

Example fix

// before
Name: path.Join(layerBasePath, rawRel) // rawRel contains control chars
// after
safe := strings.Map(func(r rune) rune { if r < 32 || r == ':' { return '_' }; return r }, rawRel)
hdr.Name = path.Join(layerBasePath, safe)

Defensive patterns

Strategy: try-catch

Validate before calling

if strings.ContainsRune(name, ':') || strings.ContainsFunc(name, func(r rune) bool { return r < 32 }) {
    return fmt.Errorf("tar-unsafe file name: %q", name)
}

Try / catch

if err != nil && strings.Contains(err.Error(), "failed to write tar header") {
    // inspect wrapped cause, rename offending file, retry
}

Prevention

Use ASCII, tar-safe file names in layer content
Sanitize generated artifact names before writing them into the layer
Unwrap and log the underlying tar error for diagnosis

When it happens

Trigger: Writing a tar header whose Name contains characters invalid for tar/USTAR encoding, or an unusually large mode value, while archiving the layer directory.

Common situations: Layer file names containing non-ASCII or control characters, names with tar-invalid sequences produced by generated build artifacts, or corrupted file metadata from a damaged filesystem.

Related errors

AI-assisted analysis of slimtoolkit/slim@81940d17fa (2026-08-31). Data as JSON: /api/errors/24d0edb7700c1149. Report an issue: GitHub.