twpayne/chezmoi · error

%s: unknown archive format

Error message

%s: unknown archive format

What it means

WalkArchive (internal/chezmoi/archive.go:119) sniffs the archive's magic bytes and dispatches to the appropriate reader (tar, zip, gzip, bzip2, xz, zstd). If the detected format does not match any supported decompressor, it returns "%s: unknown archive format" naming the format identifier found.

Source

Thrown at internal/chezmoi/archive.go:119

		if err != nil {
			return err
		}
	case ArchiveFormatTarXz:
		// Decompress with xz.
		var err error
		r, err = xz.NewReader(r)
		if err != nil {
			return err
		}
	case ArchiveFormatTarZst:
		// Decompress with zstd.
		var err error
		r, err = zstd.NewReader(r)
		if err != nil {
			return err
		}
	default:
		return fmt.Errorf("%s: unknown archive format", format)
	}
	return walkArchiveTar(r, f)
}

// isTarArchive returns if r looks like a tar archive.
func isTarArchive(r io.Reader) bool {
	tarReader := tar.NewReader(r)
	_, err := tarReader.Next()
	return err == nil
}

func implicitTarDirHeader(dir RelPath, modTime time.Time) *tar.Header {
	return &tar.Header{
		Typeflag: tar.TypeDir,
		Name:     dir.String(),
		Mode:     0o777,
		Size:     0,
		ModTime:  modTime,

View on GitHub (pinned to f901167e46)

Solutions

1. Verify the file is actually an archive: run `file <path>` and check magic bytes.
2. Re-download or regenerate the archive; ensure the URL/fetch did not return an error page.
3. Convert the archive to a supported format (tar, tar.gz, tar.bz2, tar.xz, tar.zst, zip).

Example fix

# before: URL serving HTML login page
curl -sL $URL | chezmoi archive import -
# after
curl -sfL $URL -o archive.tar.gz && file archive.tar.gz && chezmoi archive import archive.tar.gz

buf, _ := io.ReadAll(io.LimitReader(r, 512))
magic := http.DetectContentType(buf)
if magic == "text/html; charset=utf-8" {
    return fmt.Errorf("not an archive: got HTML")
}

if err := chezmoi.WalkArchive(data, fn); err != nil {
    if strings.Contains(err.Error(), "unknown archive format") {
        // inspect `file` output and re-fetch or convert the archive
    }
    return err
}

When it happens

Trigger: Calling WalkArchive (or readExternalArchive / NewArchiveReaderSystem which route through it) with data whose leading bytes match none of the supported magic numbers.

Common situations: Downloaded archive URL returned an HTML error page instead of an archive; file truncated or corrupted; using a compression format chezmoi does not support (e.g. lz4, 7z); empty file passed as an archive.

Related errors

• %s: %w
• %s: unsupported typeflag '%c'
• %s: unsupported file mode %o
• %s: unsupported mode %o
• %s: unsupported mode %o

AI-assisted analysis of twpayne/chezmoi@f901167e46 (2026-09-01). Data as JSON: /api/errors/05e8a295f57c6ba8. Report an issue: GitHub.