helm/helm · error

unknown type: %b in %s

Error message

unknown type: %b in %s

What it means

Thrown by extractTar in the OCI plugin installer when a tar entry's Typeflag is not one of the supported kinds (TypeDir, TypeReg, TypeXHeader, TypeXGlobalHeader). Helm's extractor only writes directories and regular files; any other entry type — symlinks (2), hardlinks (1), FIFOs (6), char/block devices (3/4) — aborts installation. Note the format verb is %b, so the byte prints in binary (e.g. symlinks show as 1000010).

Source

Thrown at internal/plugin/installer/oci_installer.go:253

		case tar.TypeReg:
			dir := filepath.Dir(path)
			if err := os.MkdirAll(dir, 0o755); err != nil {
				return err
			}

			outFile, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, os.FileMode(header.Mode))
			if err != nil {
				return err
			}
			defer outFile.Close()
			if _, err := io.Copy(outFile, tarReader); err != nil {
				return err
			}
		case tar.TypeXGlobalHeader, tar.TypeXHeader:
			// Skip these
			continue
		default:
			return fmt.Errorf("unknown type: %b in %s", header.Typeflag, header.Name)
		}
	}

	return nil
}

// SupportsVerification returns true since OCI plugins can be verified
func (i *OCIInstaller) SupportsVerification() bool {
	return true
}

// GetVerificationData downloads and caches plugin and provenance data from OCI registry for verification
func (i *OCIInstaller) GetVerificationData() (archiveData, provData []byte, filename string, err error) {
	slog.Debug("getting verification data for OCI plugin", "source", i.Source)

	// Download plugin data once and cache it
	if i.pluginData == nil {
		pluginDataBuffer, err := i.getter.Get(i.Source)

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Rebuild the plugin tarball without symlinks/hardlinks: replace symlinks with copies (cp -L) and repackage with tar (GNU tar stores hardlinks as TypeLink for duplicate files — deduplicate or use --hard-dereference).
2. Check for offending entries: tar -tvzf plugin.tgz | grep -E '^[hl]' lists links; anything shown must be materialized as a real file.
3. If the link is essential (e.g. platform-specific binary dispatch), restructure the plugin to use a wrapper script or platformDirs in plugin.yaml instead.
4. Push the fixed artifact and reinstall: helm plugin remove <name> && helm plugin install oci://...

Example fix

# before: build step creates a symlink
ln -s bin/helm-plugin-linux-amd64 bin/helm-plugin
# after: ship a real file (or wrapper script)
cp bin/helm-plugin-linux-amd64 bin/helm-plugin
chmod +x bin/helm-plugin

func tarHasOnlySupportedTypes(r io.Reader) (bool, error) {
    tr := tar.NewReader(r)
    for {
        h, err := tr.Next()
        if errors.Is(err, io.EOF) { return true, nil }
        if err != nil { return false, err }
        switch h.Typeflag {
        case tar.TypeDir, tar.TypeReg, tar.TypeXHeader, tar.TypeXGlobalHeader:
        default:
            return false, nil
        }
    }
}

func isSupportedTarType(flag byte) bool {
    return flag == tar.TypeDir || flag == tar.TypeReg || flag == tar.TypeXHeader || flag == tar.TypeXGlobalHeader
}

if err := installer.Install(); err != nil {
    if strings.Contains(err.Error(), "unknown type:") {
        // repack artifact: materialize links as real files (--dereference, cp -L)
    }
}

When it happens

Trigger: Installing an OCI plugin whose tar layer contains symlinks (most common: plugin ships a bin symlink or was built from a node/python tree with linked dependencies), hardlinked files, FIFOs or device nodes; archives produced by tools that store hardlinks for duplicate files (e.g. some deterministic build tooling).

Common situations: Plugin authors using 'ln -s' in their build script; wasm/native binaries shared across directories via hardlinks; packaging on macOS where some tools emit symlinks for .dylibs; copying node_modules into the distribution tarball.

Related errors

• failed to extract plugin: %w
• failed to create plugin tarball: %w
• cannot push directory, must provide chart archive (.tgz)
• failed to create cache directory: %w
• error unpacking subchart tar in %s: expected %s, got %s

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/be7fa2e003452a2a. Report an issue: GitHub.