juicedata/juicefs · error

read stage footer data: %w

Error message

read stage footer data: %w

What it means

Returned by stageFooter.unmarshal when reading the footer payload bytes (tier metadata) from the staged cache file fails after the header validated. An I/O error at this point means disk trouble or concurrent truncation.

Source

Thrown at pkg/chunk/disk_cache_file.go:102

		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
	}
	if f.Tier > maxTierID {
		f.Tier = 0 // ignore unknown/corrupted tier, fall back to the default
	}
	return nil
}

var (
	stageFooterBaseLen int
	stageFooterPad     [4][]byte
	stageFooterMagic   = uint16(0x4653)
)

func init() {
	b, err := msgpack.Marshal(&stageFooter{Pad: make([]byte, 0)})

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Remove the unreadable staged file; verify cache disk health

When it happens

Trigger: Thrown at pkg/chunk/disk_cache_file.go:102 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/5a299cd30ada559b. Report an issue: GitHub.