juicedata/juicefs · error

read stage footer header: %w

Error message

read stage footer header: %w

What it means

Returned by stageFooter.unmarshal when reading the 4-byte staged-file footer header at the expected offset fails (I/O error). The footer records which tier a staged cache file belongs to; if it cannot be read the staged file cannot be trusted for upload.

Source

Thrown at pkg/chunk/disk_cache_file.go:88

	if err != nil {
		return nil, err
	}

	buff := make([]byte, 0, 4+len(data))
	buff = binary.BigEndian.AppendUint16(buff, stageFooterMagic)
	buff = binary.BigEndian.AppendUint16(buff, uint16(len(data)))
	buff = append(buff, data...)
	return buff, nil
}

func (f *stageFooter) unmarshal(cf *cacheFile) error {
	if cf.footerOff == 0 {
		f.Tier = 0 // no footer, fall back to the default
		return nil
	}
	var hdr [4]byte
	if _, err := cf.File.ReadAt(hdr[:], cf.footerOff); err != nil {
		return fmt.Errorf("read stage footer header: %w", err)
	}
	if magic := binary.BigEndian.Uint16(hdr[:2]); magic != stageFooterMagic {
		return fmt.Errorf("invalid stage footer magic %#04x", magic)
	}
	size := int64(binary.BigEndian.Uint16(hdr[2:4]))
	if size == 0 {
		return fmt.Errorf("invalid stage footer length %d", size)
	}
	if cf.footerOff+4+size != cf.size {
		return fmt.Errorf("stage footer size mismatch: offset %d, size %d, file size %d", cf.footerOff, size, cf.size)
	}
	buf := make([]byte, size)
	if _, err := cf.File.ReadAt(buf, cf.footerOff+4); err != nil {
		return fmt.Errorf("read stage footer data: %w", err)
	}
	if err := msgpack.Unmarshal(buf, f); err != nil {
		return err
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Discard the damaged staged cache file so it can be re-staged and uploaded
2. Check disk health of the cache directory

When it happens

Trigger: Thrown at pkg/chunk/disk_cache_file.go:88 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/467bb4907f2ebe69. Report an issue: GitHub.