golang/go · error · entryNotFoundError

invalid header

Error message

invalid header

What it means

The entry file has the correct size (exactly entrySize bytes) but its header bytes don't match the expected format 'v1 <hex-action-id> <hex-output-id> <size> <timestamp>\n'. The code checks for the 'v1' prefix, space delimiters at specific offsets, and a trailing newline. A mismatch means the file content was corrupted despite having the right length.

Source

Thrown at src/cmd/go/internal/cache/cache.go:222

	}
	f, err := os.Open(c.fileName(id, "a"))
	if err != nil {
		return missing(err)
	}
	defer f.Close()
	entry := make([]byte, entrySize+1) // +1 to detect whether f is too long
	if n, err := io.ReadFull(f, entry); n > entrySize {
		return missing(errors.New("too long"))
	} else if err != io.ErrUnexpectedEOF {
		if err == io.EOF {
			return missing(errors.New("file is empty"))
		}
		return missing(err)
	} else if n < entrySize {
		return missing(errors.New("entry file incomplete"))
	}
	if entry[0] != 'v' || entry[1] != '1' || entry[2] != ' ' || entry[3+hexSize] != ' ' || entry[3+hexSize+1+hexSize] != ' ' || entry[3+hexSize+1+hexSize+1+20] != ' ' || entry[entrySize-1] != '\n' {
		return missing(errors.New("invalid header"))
	}
	eid, entry := entry[3:3+hexSize], entry[3+hexSize:]
	eout, entry := entry[1:1+hexSize], entry[1+hexSize:]
	esize, entry := entry[1:1+20], entry[1+20:]
	etime, entry := entry[1:1+20], entry[1+20:]
	var buf [HashSize]byte
	if _, err := hex.Decode(buf[:], eid); err != nil {
		return missing(fmt.Errorf("decoding ID: %v", err))
	} else if buf != id {
		return missing(errors.New("mismatched ID"))
	}
	if _, err := hex.Decode(buf[:], eout); err != nil {
		return missing(fmt.Errorf("decoding output ID: %v", err))
	}
	i := 0
	for i < len(esize) && esize[i] == ' ' {
		i++
	}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Run go clean -cache to purge all entries and rebuild
2. Run hardware diagnostics — memtest86 for RAM, SMART checks for disk health
3. Ensure a consistent Go version across all builds that share the same GOCACHE directory
4. Move the cache to more reliable storage if corruption recurs

Example fix

// before: corrupt header bytes in cache entry
// $ go build ./... # fails with 'cache entry not found: invalid header'

// after: clean cache and verify hardware
// $ go clean -cache && go build ./...
// $ smartctl -a /dev/sda  # check disk health if issue recurs

// Validate cache format compatibility before using a shared cache.
// Check the Go version matches what created the cache.
func checkCacheVersionCompat(cacheDir string) error {
    // The cache log file records the Go version that created the cache
    logPath := filepath.Join(cacheDir, "log.txt")
    data, err := os.ReadFile(logPath)
    if err != nil {
        return nil // no log, assume fresh cache
    }
    currentVersion := runtime.Version()
    if !bytes.Contains(data, []byte(currentVersion)) {
        return fmt.Errorf("cache may be from a different Go version; run go clean -cache")
    }
    return nil
}

func isInvalidHeader(err error) bool {
    return err != nil && strings.Contains(err.Error(), "invalid header")
}

// entry, err := cache.Get(id)
// if err != nil {
//     // Invalid header — corrupt or version-incompatible entry.
//     // Rebuild the output from source.
//     output = rebuild()
// }

When it happens

Trigger: DiskCache.get(id) reads a full entrySize bytes (the valid-length case) but the header validation on entry[0], entry[1], entry[2], entry[3+hexSize], and other delimiter positions fails — wrong version marker, missing spaces, or wrong trailing byte.

Common situations: Byte-level corruption from bad RAM, disk errors, or filesystem bugs; a different Go toolchain version writing entries with a different format version to the same cache directory; cosmic ray bit-flips on unreliable hardware; manual editing of cache files.

Related errors

• too long
• file is empty
• entry file incomplete
• mismatched ID
• negative size

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