Introduction

The Go error archive/tar: write too long usually means you wrote more bytes for an entry than the tar header declared for that entry. This is not normally a generic filesystem size limit problem. It is a mismatch between the tar.Header.Size value and the actual number of bytes sent to the tar writer for that file.

Why the Error Happens

When you create a tar entry with Go's archive/tar package, you first write a header and then stream the file contents. The header includes the expected byte length.

If the header says the file is 100 bytes long but you write 120 bytes, the tar writer detects the overflow and raises:

archive/tar: write too long

That is the core failure mode.

A Correct Minimal Example

A valid tar creation flow looks like this:

1package main
2
3import (
4    "archive/tar"
5    "bytes"
6    "fmt"
7)
8
9func main() {
10    var buf bytes.Buffer
11    tw := tar.NewWriter(&buf)
12
13    content := []byte("hello tar\n")
14    hdr := &tar.Header{
15        Name: "hello.txt",
16        Mode: 0600,
17        Size: int64(len(content)),
18    }
19
20    if err := tw.WriteHeader(hdr); err != nil {
21        panic(err)
22    }
23    if _, err := tw.Write(content); err != nil {
24        panic(err)
25    }
26    if err := tw.Close(); err != nil {
27        panic(err)
28    }
29
30    fmt.Println("tar created:", buf.Len())
31}

The important part is that Size matches the exact number of bytes written afterward.

A Common Broken Pattern

The error often appears when code computes the header size from one value and writes a different value later.

For example:

1content := []byte("hello")
2hdr := &tar.Header{Name: "a.txt", Size: 3}
3
4_ = tw.WriteHeader(hdr)
5_, err := tw.Write(content)

Here the header claims the entry is 3 bytes long, but the code writes 5 bytes. That triggers archive/tar: write too long.

The same bug appears when:

• string length is counted before encoding changes
• compressed bytes are written after an uncompressed size was recorded
• file content changes after the header is created
• a loop reuses a header incorrectly

Use the Real File Size for Disk Files

When archiving files from disk, the safest path is to read the file metadata and use the actual file size.

1package main
2
3import (
4    "archive/tar"
5    "io"
6    "os"
7)
8
9func addFile(tw *tar.Writer, path string) error {
10    file, err := os.Open(path)
11    if err != nil {
12        return err
13    }
14    defer file.Close()
15
16    info, err := file.Stat()
17    if err != nil {
18        return err
19    }
20
21    hdr := &tar.Header{
22        Name: info.Name(),
23        Mode: 0600,
24        Size: info.Size(),
25    }
26
27    if err := tw.WriteHeader(hdr); err != nil {
28        return err
29    }
30
31    _, err = io.Copy(tw, file)
32    return err
33}

This keeps the header size aligned with the real file content.

Be Careful With Generated Content

In-memory content is where this error shows up most often. If you generate JSON, template output, or compressed data on the fly, compute the bytes first and use the exact final length in the header.

A safe pattern is:

1. generate the full byte slice
2. set Size to len(data)
3. write the header
4. write exactly that byte slice

Do not guess the length from an earlier representation.

Close the Tar Writer Properly

While write too long is specifically about an oversized write, remember to close the tar writer at the end. Closing flushes the tar end markers and finalizes the archive.

if err := tw.Close(); err != nil {
    panic(err)
}

This does not fix the size mismatch error, but it is part of producing a valid archive.

Common Pitfalls

• Setting tar.Header.Size from the wrong value is the main cause of archive/tar: write too long.
• Writing transformed or re-encoded content after computing the size from the original representation creates a mismatch.
• Reusing headers across loop iterations can accidentally preserve the wrong size for the next file.
• Assuming the error is about total tarball size or disk capacity sends debugging in the wrong direction. It is usually an entry-size mismatch.
• Forgetting to generate the full content before writing the header makes it harder to guarantee the declared size is correct.

Summary

• 'archive/tar: write too long usually means the tar header size is smaller than the actual bytes written for that entry.'
• In Go, tar.Header.Size must exactly match the content length that follows.
• For files from disk, use Stat() to get the real size.
• For generated content, compute the final byte slice first, then write the header.
• Debug the per-entry size accounting, not generic tarball limits.