How to fix fatal: Unknown archive format 'unknown' in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 135 views

This error occurs when you specify an archive format that Git doesn't recognize or support. The fix involves using a valid format like tar, zip, or tar.gz, or checking your Git version for format availability.

Quick fix

Fixes fatal: Unknown archive format 'unknown'

git archive --list
  1. List available archive formats
  2. Check your Git version
  3. Use a supported format name
  4. Configure custom archive formats
git — error
git archive --list
fatal: Unknown archive format 'unknown'

What this error means

When you run `git archive` with the `--format` option, Git attempts to create an archive in the specified format. If Git doesn't recognize the format you've specified, it fails with "fatal: Unknown archive format". Git has built-in support for a limited set of archive formats. The core formats are `tar` (the default) and `zip`. Modern versions of Git also support `tar.gz` and `tgz` natively using an internal gzip implementation. Additional formats like `tar.xz` can be configured through Git's `tar.<format>.command` configuration option. This error commonly occurs when users misspell a format name, try to use a format that requires a newer Git version, or attempt to use custom formats that haven't been configured. Older Git versions (before 1.8.0) don't support `tar.gz` natively, which catches many developers off guard when working on older systems.

Typical symptoms

  • git archive command fails immediately with 'fatal: Unknown archive format' message
  • Automated build scripts that create release archives fail unexpectedly
  • CI/CD pipelines using git archive break after migrating to different servers
  • Format works on local machine but fails on production server with older Git
  • Export scripts that worked previously fail after system updates or migrations

Common causes

  1. The specified format name is misspelled (e.g., 'gzip' instead of 'tar.gz')
  2. Your Git version is too old to support the requested format (tar.gz requires Git 1.8+)
  3. You're trying to use a custom format that hasn't been configured via tar.<format>.command
  4. Using a format extension that Git doesn't automatically recognize (e.g., 'tar.bz2' without configuration)
  5. Remote archive format not enabled when using git archive with remote repositories
  6. Confusing archive format names with compression tool names (e.g., 'gzip' vs 'tar.gz')

How to fix "fatal: Unknown archive format 'unknown'"

1List available archive formats

First, check which archive formats your Git installation supports:

bash
git archive --list

This typically outputs:

bash
tar
tgz
tar.gz
zip

If you don't see the format you need, either your Git version is too old or you need to configure a custom format.

2Check your Git version

Some formats like tar.gz and tgz were added in newer Git versions:

bash
git --version

Format support by version:
- tar, zip: All Git versions
- tar.gz, tgz: Git 1.8.0+ (native gzip support)
- Custom formats: Git 1.4.3+ (via configuration)

If you're on an older version, upgrade Git or use a workaround (see step 5).

3Use a supported format name

Make sure you're using the exact format name Git expects:

bash
# Correct format names
git archive --format=tar HEAD > archive.tar
git archive --format=zip HEAD > archive.zip
git archive --format=tar.gz HEAD > archive.tar.gz
git archive --format=tgz HEAD > archive.tgz

# Common mistakes (these will fail):
git archive --format=gzip HEAD      # Wrong: 'gzip' is not a format
git archive --format=targz HEAD     # Wrong: missing dot
git archive --format=tar.bz2 HEAD   # Wrong: not built-in, needs config

You can also let Git infer the format from the output filename:

bash
git archive -o release.zip HEAD      # Automatically uses zip format
git archive -o release.tar.gz HEAD   # Automatically uses tar.gz format
4Configure custom archive formats

For formats like tar.xz or tar.bz2, you need to configure them in Git:

For tar.xz (LZMA compression):

bash
git config --global tar.tar.xz.command "xz -c"

For tar.bz2 (bzip2 compression):

bash
git config --global tar.tar.bz2.command "bzip2 -c"

Now you can use these formats:

bash
git archive --format=tar.xz HEAD > archive.tar.xz
git archive --format=tar.bz2 HEAD > archive.tar.bz2

To verify your configuration:

bash
git config --get-regexp 'tar..*.command'
5Workaround for older Git versions

If you can't upgrade Git and need tar.gz output, pipe through gzip manually:

bash
git archive --format=tar HEAD | gzip > archive.tar.gz

For other compression formats:

bash
# bzip2 compression
git archive --format=tar HEAD | bzip2 > archive.tar.bz2

# xz compression
git archive --format=tar HEAD | xz > archive.tar.xz

# zstd compression (if available)
git archive --format=tar HEAD | zstd > archive.tar.zst

This approach works with any Git version that supports the base tar format.

6Verify the archive was created correctly

After creating your archive, verify it's valid:

For tar archives:

bash
tar -tzf archive.tar.gz | head -20

For zip archives:

bash
unzip -l archive.zip | head -20

If you get errors here, the archive may have been corrupted or the format specification was wrong.

Advanced notes

### Remote Archive Considerations

When using git archive with remote repositories, the remote server must have the format enabled. For custom formats, set:

bash
git config tar.<format>.remote true

The tar.gz and tgz formats have remote = true by default in modern Git versions.

Note that some Git hosting services (like Bitbucket Cloud) don't support git archive over HTTPS at all. You may see "Operation not supported by protocol" errors. In these cases:

1. Clone the repository locally first
2. Use SSH instead of HTTPS (if supported)
3. Use the hosting service's API to download archives instead

### Compression Level Options

For zip archives, you can control compression level with the -<digit> option:

bash
git archive -9 --format=zip HEAD > highly-compressed.zip  # Best compression
git archive -0 --format=zip HEAD > store-only.zip         # No compression (fastest)

### CI/CD Pipeline Tips

When using git archive in CI/CD pipelines:

1. Check Git version early in your pipeline to catch format issues
2. Use explicit format flags rather than relying on filename inference
3. Fall back to pipe-through-gzip for maximum compatibility:

bash
if git archive --list | grep -q tar.gz; then
  git archive --format=tar.gz HEAD > archive.tar.gz
else
  git archive --format=tar HEAD | gzip > archive.tar.gz
fi

### Performance Considerations

The built-in tar.gz format uses Git's internal gzip implementation, which may behave slightly differently than system gzip. For reproducible builds, consider:

bash
git archive --format=tar --prefix=myproject/ HEAD | gzip -n > archive.tar.gz

The -n flag to gzip omits the timestamp, making the output deterministic.

Frequently asked questions

What does "fatal: Unknown archive format 'unknown'" mean?
When you run git archive with the --format option, Git attempts to create an archive in the specified format. If Git doesn't recognize the format you've specified, it fails with "fatal: Unknown archive format". Git has built-in support for a limited set of archive formats.
How do I fix "fatal: Unknown archive format 'unknown'"?
This error occurs when you specify an archive format that Git doesn't recognize or support. The fix involves using a valid format like tar, zip, or tar.gz, or checking your Git version for format availability.
What causes "fatal: Unknown archive format 'unknown'"?
The specified format name is misspelled (e.g., 'gzip' instead of 'tar.gz') Your Git version is too old to support the requested format (tar.gz requires Git 1.8+) You're trying to use a custom format that hasn't been configured via tar.<format>.command
Is the "fatal: Unknown archive format 'unknown'" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading