What causes "file too large (%d bytes > %d bytes)" in golang/go?

Do not embed files larger than 2GB — load them at runtime with os.Open or os.ReadFile

file too large (%d bytes > %d bytes)

Error message

file too large (%d bytes > %d bytes)

What it means

The Go toolchain imposes a maximum symbol size of obj.MaxSymSize (2GB, defined as int64(2e9) in cmd/internal/obj). When an embedded file exceeds this limit, the compiler rejects it with this error showing the actual size and the limit. This is a hard constraint of the object file format.

Source

Thrown at src/cmd/compile/internal/staticdata/data.go:161

		}
		var sym *obj.LSym
		if readonly {
			sym = StringSym(pos, string(data))
		} else {
			sym = slicedata(pos, string(data))
		}
		if len(hashBytes) > 0 {
			sum := hash.Sum32(data)
			copy(hashBytes, sum[:])
		}
		return sym, size, nil
	}
	if size > maxFileSize {
		// ggloblsym takes an int32,
		// and probably the rest of the toolchain
		// can't handle such big symbols either.
		// See golang.org/issue/9862.
		return nil, 0, fmt.Errorf("file too large (%d bytes > %d bytes)", size, maxFileSize)
	}

	// File is too big to read and keep in memory.
	// Compute hashBytes if needed for read-only content hashing or if the caller wants it.
	var sum []byte
	if readonly || len(hashBytes) > 0 {
		h := hash.New32()
		n, err := io.Copy(h, f)
		if err != nil {
			return nil, 0, err
		}
		if n != size {
			return nil, 0, fmt.Errorf("file changed between reads")
		}
		sum = h.Sum(nil)
		copy(hashBytes, sum)
	}

View on GitHub (pinned to b6b368adc5)

Solutions

Do not embed files larger than 2GB — load them at runtime with os.Open or os.ReadFile
Split large files into chunks under the limit and embed each chunk separately
Use a content-addressed external storage strategy and download large assets at install or runtime
Review your embed patterns to ensure they don't accidentally match large files

Example fix

// before
//go:embed assets/large_model.bin (3GB)
var modelData []byte

// after — load at runtime
func loadModel() ([]byte, error) {
    return os.ReadFile(filepath.Join(assetDir, "large_model.bin"))
}

Defensive patterns

Strategy: validation

Validate before calling

// Check embedded file sizes against the 2GB limit
const maxEmbedSize = int64(2e9) // obj.MaxSymSize

func checkEmbedFileSizes(dir string) error {
    return filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {
        if err != nil {
            return err
        }
        if !info.IsDir() && info.Size() > maxEmbedSize {
            return fmt.Errorf("%s is %d bytes, exceeds embed limit of %d bytes — use runtime loading instead", path, info.Size(), maxEmbedSize)
        }
        return nil
    })
}

Prevention

Never embed files larger than 2GB — load them at runtime instead
Review embed patterns to ensure they don't accidentally match large files
Use .embedignore or directory structure to exclude large data files from embed patterns
Consider compressing large files before embedding if they must be in the binary

When it happens

Trigger: Attempting to //go:embed a file larger than 2GB. The size is determined by os.FileInfo.Size() from stat, so sparse files may also trigger this if their reported size exceeds the limit.

Common situations: Accidentally embedding large data files (SQLite databases, video, ML model weights, large datasets). Not realizing that //go:embed loads the entire file into the compiled binary. Using embed.FS with a directory containing very large files.

Related errors

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/d46573f1b1f131d1. Report an issue: GitHub.