larksuite/cli · error

tar: %w

Error message

tar: %w

What it means

pluginExtractTGZ wraps tar.Reader.Next failures with 'tar: %w'. The gzip layer succeeded but the tar stream is corrupt, truncated, or contains unreadable headers, so extraction aborts. It is an intermediate error; callers wrap it as typed.

Source

Thrown at shortcuts/apps/plugin_common.go:367

// pluginExtractTGZ extracts a gzipped tar archive into destDir, stripping the
// first path component (npm convention: tarballs contain a "package/" prefix).
// Path traversal entries are silently skipped.
func pluginExtractTGZ(r io.Reader, destDir string) error {
	gz, err := gzip.NewReader(r)
	if err != nil {
		return fmt.Errorf("gzip: %w", err) //nolint:forbidigo // intermediate helper error; callers wrap as typed
	}
	defer gz.Close()

	cleanDest := filepath.Clean(destDir) + string(filepath.Separator)
	tr := tar.NewReader(gz)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			break
		}
		if err != nil {
			return fmt.Errorf("tar: %w", err) //nolint:forbidigo // intermediate helper error; callers wrap as typed
		}

		name := pluginStripFirstComponent(hdr.Name)
		if name == "" {
			continue
		}
		if strings.Contains(name, "..") {
			continue
		}

		target := filepath.Join(destDir, name)
		if !strings.HasPrefix(filepath.Clean(target)+string(filepath.Separator), cleanDest) &&
			filepath.Clean(target) != filepath.Clean(destDir) {
			continue
		}

		switch hdr.Typeflag {
		case tar.TypeSymlink, tar.TypeLink:

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Verify the payload is a real tarball: `tar -tzf plugin.tgz` should list package/... entries
2. Re-download or re-pack the archive (`tar -czf`) and retry the install
3. Check the download completed fully (compare byte size/checksum)

Example fix

// before
gzip -9 plugin.js && mv plugin.js.gz plugin.tgz  # not a tarball
// after
tar -czf plugin.tgz --transform 's,^,package/,' plugin.js

// sanity-check the archive lists a package/ prefix before installing
// tar -tzf plugin.tgz | head  ->  expect "package/..." entries

if strings.HasPrefix(err.Error(), "tar: ") {
	// the payload passed gzip but not tar: re-download or re-pack as a real tarball
}

When it happens

Trigger: A gzip-valid but non-tar payload (e.g. gzip of a plain file), a truncated tarball, or a tarball with malformed headers fed to plugin install.

Common situations: Renaming a .gz (single file) to .tgz, partial downloads, or archives produced by broken tooling.

Related errors

• gzip: %w
• annotated_csv did not parse into the rows the server reporte
• --max-sheets must be at least 1
• copy tar entry: %w; close file: %w

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/799862b73fd239a4. Report an issue: GitHub.