juicedata/juicefs · error

invalid stage footer length %d

Error message

invalid stage footer length %d

What it means

The staged cache file's footer declares a payload size of zero after the magic number was validated. Indicates the footer is truncated or corrupted (length field never written or zeroed), so the tiering metadata cannot be trusted and the footer is rejected.

Source

Thrown at pkg/chunk/disk_cache_file.go:95

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

var (

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Drop the malformed staged cache file and let it be re-staged

When it happens

Trigger: Thrown at pkg/chunk/disk_cache_file.go:95 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/023a15864b63b0f4. Report an issue: GitHub.