hyperledger/fabric · error

invalid file type '%v' contained in archive for file '%s'

Error message

invalid file type '%v' contained in archive for file '%s'

What it means

Untar only supports regular files and directories; any other tar entry type (symlinks, hardlinks, devices, FIFOs, etc.) hits the default case and returns this error naming the typeflag and entry. It prevents unexpected/special file types from entering the build context.

Source

Thrown at core/container/externalbuilder/tar.go:71

			}
		case tar.TypeReg:
			if err := os.MkdirAll(filepath.Dir(target), 0o700); err != nil {
				return errors.WithMessagef(err, "could not create directory '%s'", filepath.Dir(header.Name))
			}

			f, err := os.OpenFile(target, os.O_CREATE|os.O_RDWR, os.FileMode(header.Mode))
			if err != nil {
				return errors.WithMessagef(err, "could not create file '%s'", header.Name)
			}

			// copy over contents
			if _, err := io.Copy(f, tr); err != nil {
				return err
			}

			f.Close()
		default:
			return errors.Errorf("invalid file type '%v' contained in archive for file '%s'", header.Typeflag, header.Name)
		}
	}
}

// ValidPath checks to see if the path is absolute, or if it is a
// relative path higher in the tree.  In these cases it returns false.
func ValidPath(uncleanPath string) bool {
	// sanitizedPath will eliminate non-prefix instances of '..', as well
	// as strip './'
	sanitizedPath := filepath.Clean(uncleanPath)

	switch {
	case filepath.IsAbs(sanitizedPath):
		return false
	case strings.HasPrefix(sanitizedPath, ".."+string(filepath.Separator)) || sanitizedPath == "..":
		// Path refers either to the parent, or a directory relative to the parent (but allows ..foo or ... for instance)
		return false
	default:

View on GitHub (pinned to 2736b63f8f)

Solutions

1. Dereference links when archiving: use 'tar -ch' (--dereference) so entries are stored as regular files.
2. Exclude special files from the archive (tar --exclude patterns for symlinks, sockets, pipes).
3. Pre-process the source tree to remove or resolve symlinks before packaging.
4. If links are genuinely required, modify the packager to represent them differently and extend Untar's supported typeflags.

Example fix

// before
tar -cf pkg.tar ./output   // output contains symlinks
// after
tar -chf pkg.tar ./output  // dereference links into regular files

hdrs, err := tarHeaderTypes(pkgPath)
if err != nil { return err }
for name, tf := range hdrs {
    if tf != tar.TypeReg && tf != tar.TypeDir {
        return fmt.Errorf("unsupported type %v for %s", tf, name)
    }
}

if err := externalbuilder.Untar(dst, r); err != nil {
    if strings.Contains(err.Error(), "invalid file type") {
        return fmt.Errorf("repackage archive without links/special files: %w", err)
    }
    return err
}

When it happens

Trigger: Archiving a directory tree that contains symbolic links, hard links, sockets, FIFOs, or device nodes (e.g. GNU tar capturing node_modules symlinks) and feeding it to Untar.

Common situations: Packaging symlink-heavy trees (node_modules, venv) on Linux/macOS; tars generated with 'tar -cf' over directories containing /dev entries or sockets; build tool caches that include links.

Related errors

• illegal file name in payload: %s
• failed calculating FileInfoHeader: %s
• %s is mandatory and cannot be empty
• enrollment certificate isn't a valid PEM block
• failed to decode PEM block from %s

AI-assisted analysis of hyperledger/fabric@2736b63f8f (2026-09-04). Data as JSON: /api/errors/342d947f91412ec4. Report an issue: GitHub.