plandex-ai/plandex · error

failed to read tar header: %w

Error message

failed to read tar header: %w

What it means

While iterating the extracted tar archive, tarReader.Next() advancing to the next header can return a non-EOF error; doUpgrade wraps it as 'failed to read tar header: %w'. This means the archive is corrupt partway through (usually a truncated or tampered download).

Source

Thrown at app/cli/upgrade.go:142

	if err != nil {
		return fmt.Errorf("failed to seek in temporary file: %w", err)
	}

	// Now, extract the binary from the tempFile
	gzr, err := gzip.NewReader(tempFile)
	if err != nil {
		return fmt.Errorf("failed to create gzip reader: %w", err)
	}
	defer gzr.Close()

	tarReader := tar.NewReader(gzr)
	for {
		header, err := tarReader.Next()
		if err == io.EOF {
			break // End of archive
		}
		if err != nil {
			return fmt.Errorf("failed to read tar header: %w", err)
		}

		// Check if the current file is the binary
		if header.Typeflag == tar.TypeReg && (header.Name == "plandex" || header.Name == "plandex.exe") {
			err = update.Apply(tarReader, update.Options{})
			if err != nil {
				if errors.Is(err, fs.ErrPermission) {
					return fmt.Errorf("failed to apply update due to permission error; please try running your command again with 'sudo': %w", err)
				}
				return fmt.Errorf("failed to apply update: %w", err)
			}
			break
		}
	}

	return nil
}

View on GitHub (pinned to e2d772072e)

Solutions

1. Retry the upgrade to re-download the archive.
2. Verify checksum of the downloaded release asset if possible.
3. Check for a proxy/VPN that truncates large transfers.
4. Download and install the release manually.

if _, err := tarReader.Next(); err != nil && err != io.EOF {
	return fmt.Errorf("failed to read tar header: %w (archive may be truncated; retry the upgrade)", err)
}

When it happens

Trigger: The tar stream inside the gzip reader is malformed: the download was cut off mid-archive, the file was corrupted in transit, or a non-tar payload got this far (proxy-modified content).

Common situations: Flaky network dropping the connection mid-download so the file is truncated; disk corruption; MITM proxy rewriting content; CDN serving partial content.

Related errors

• failed to create gzip reader: %w
• connection to plan stream timed out due to missing heartbeat
• error loading accounts: %v
• error signing in to new account: %v
• error selecting account: %v

AI-assisted analysis of plandex-ai/plandex@e2d772072e (2026-09-05). Data as JSON: /api/errors/a065764b59a21f6e. Report an issue: GitHub.