{"record":{"id":"24d0edb7700c1149","repo":"slimtoolkit/slim","slug":"failed-to-write-tar-header-w","errorCode":null,"errorMessage":"failed to write tar header: %w","messagePattern":"failed to write tar header: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/imagebuilder/internalbuilder/engine.go","lineNumber":308,"sourceCode":"\t\thdr := &tar.Header{\n\t\t\tName: path.Join(layerBasePath, filepath.ToSlash(rel)),\n\t\t\tMode: int64(info.Mode()),\n\t\t}\n\n\t\tif !info.IsDir() {\n\t\t\thdr.Size = info.Size()\n\t\t}\n\n\t\tif info.Mode().IsDir() {\n\t\t\thdr.Typeflag = tar.TypeDir\n\t\t} else if info.Mode().IsRegular() {\n\t\t\thdr.Typeflag = tar.TypeReg\n\t\t} else {\n\t\t\treturn fmt.Errorf(\"not implemented archiving file type %s (%s)\", info.Mode(), rel)\n\t\t}\n\n\t\tif err := tw.WriteHeader(hdr); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to write tar header: %w\", err)\n\t\t}\n\t\tif !info.IsDir() {\n\t\t\tf, err := os.Open(fp)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tif _, err := io.Copy(tw, f); err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to read file into the tar: %w\", err)\n\t\t\t}\n\t\t\tf.Close()\n\t\t}\n\t\treturn nil\n\t})\n\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to scan files: %w\", err)\n\t}\n\tif err := tw.Close(); err != nil {","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/slimtoolkit/slim/blob/81940d17fa112cc678e32209214bcb2355cb3004/pkg/imagebuilder/internalbuilder/engine.go#L290-L326","documentation":"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.","triggerScenarios":"Writing a tar header whose Name contains characters invalid for tar/USTAR encoding, or an unusually large mode value, while archiving the layer directory.","commonSituations":"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.","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."],"exampleFix":"// before\nName: path.Join(layerBasePath, rawRel) // rawRel contains control chars\n// after\nsafe := strings.Map(func(r rune) rune { if r < 32 || r == ':' { return '_' }; return r }, rawRel)\nhdr.Name = path.Join(layerBasePath, safe)","handlingStrategy":"try-catch","validationCode":"if strings.ContainsRune(name, ':') || strings.ContainsFunc(name, func(r rune) bool { return r < 32 }) {\n    return fmt.Errorf(\"tar-unsafe file name: %q\", name)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to write tar header\") {\n    // inspect wrapped cause, rename offending file, retry\n}","preventionTips":["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"],"tags":["tar","encoding","image-build"],"backgroundTag":"tar-header-write-failed","analyzedSha":"81940d17fa112cc678e32209214bcb2355cb3004","analyzedAt":"2026-08-31T23:06:12.682Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}