What causes "file incomplete" in golang/go?

Run go clean -cache to remove entries whose output files are inconsistent

golang/go · error · entryNotFoundError

file incomplete

Error message

file incomplete

What it means

In GetFile(), after successfully reading the entry metadata via c.Get(id), the actual output data file on disk has a different size than what the entry header declares (entry.Size). The output file was truncated or extended after the entry was written. This is a post-metadata integrity check on the output data file specifically.

Source

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

	c.markUsed(c.fileName(id, "a"))

	return Entry{buf, size, time.Unix(0, tm)}, nil
}

// GetFile looks up the action ID in the cache and returns
// the name of the corresponding data file.
func GetFile(c Cache, id ActionID) (file string, entry Entry, err error) {
	entry, err = c.Get(id)
	if err != nil {
		return "", Entry{}, err
	}
	file = c.OutputFile(entry.OutputID)
	info, err := os.Stat(file)
	if err != nil {
		return "", Entry{}, &entryNotFoundError{Err: err}
	}
	if info.Size() != entry.Size {
		return "", Entry{}, &entryNotFoundError{Err: errors.New("file incomplete")}
	}
	return file, entry, nil
}

// GetBytes looks up the action ID in the cache and returns
// the corresponding output bytes.
// GetBytes should only be used for data that can be expected to fit in memory.
func GetBytes(c Cache, id ActionID) ([]byte, Entry, error) {
	entry, err := c.Get(id)
	if err != nil {
		return nil, entry, err
	}
	data, _ := os.ReadFile(c.OutputFile(entry.OutputID))
	if sha256.Sum256(data) != entry.OutputID {
		return nil, entry, &entryNotFoundError{Err: errors.New("bad checksum")}
	}
	return data, entry, nil
}

View on GitHub (pinned to b6b368adc5)

Solutions

Run go clean -cache to remove entries whose output files are inconsistent
Check disk space on the GOCACHE partition (df -h)
Verify no external tool modifies cache output files
Run filesystem integrity checks

Example fix

// before: output file size mismatch
// $ go build ./... # fails with 'cache entry not found: file incomplete'

// after: clean cache
// $ go clean -cache && go build ./...

Defensive patterns

Strategy: try-catch

Validate before calling

// Before using a cached output file, verify it exists and has the expected size.
func validateOutputFile(path string, expectedSize int64) error {
    info, err := os.Stat(path)
    if err != nil {
        return err
    }
    if info.Size() != expectedSize {
        return fmt.Errorf("output file %s is %d bytes, expected %d", path, info.Size(), expectedSize)
    }
    return nil
}

Type guard

func isFileIncomplete(err error) bool {
    return err != nil && strings.Contains(err.Error(), "file incomplete")
}

Try / catch

// file, entry, err := cache.GetFile(c, id)
// if err != nil {
//     // File incomplete — output data file is truncated.
//     // Treat as miss and rebuild.
//     output = rebuild()
// }

Prevention

Ensure sufficient disk space during builds to prevent truncated output writes
Avoid interrupting builds mid-compilation
Exclude GOCACHE from backup/sync tools that may truncate files
Run go clean -cache if output files are consistently incomplete

When it happens

Trigger: GetFile(c, id) calls c.Get(id) successfully to obtain the Entry, then os.Stat(file) returns file info whose Size() != entry.Size. The file path comes from c.OutputFile(entry.OutputID).

Common situations: Output file truncated by a crash or power loss during the write of the output data; disk full condition after the metadata was written but before the output completed; external process (backup sync, antivirus) truncated the output file; filesystem inconsistency.

Related errors

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