juicedata/juicefs · error

failed to read segment %s length: %v

Error message

failed to read segment %s length: %v

What it means

After reading the segment type, BakSegment.Unmarshal reads the 8-byte big-endian segment length with binary.Read. This error is thrown when that read fails, typically io.EOF/io.ErrUnexpectedEOF — the stream ended between the type byte and the complete length field. It signals a truncated or corrupt backup stream, since a valid segment always carries a full 8-byte length after its type.

Source

Thrown at pkg/meta/backup.go:359

	if n, err := w.Write(data); err != nil || n != len(data) {
		return 0, fmt.Errorf("failed to write segment data %s: err %w, write len %d, expect len %d", s, err, n, len(data))
	}

	return binary.Size(s.typ) + binary.Size(s.len) + len(data), nil
}

func (s *BakSegment) Unmarshal(r io.Reader) error {
	if err := binary.Read(r, binary.BigEndian, &s.typ); err != nil {
		return fmt.Errorf("failed to read segment type: %v", err)
	}

	if s.typ == BakEOS {
		return errBakEOF
	}

	if err := binary.Read(r, binary.BigEndian, &s.len); err != nil {
		return fmt.Errorf("failed to read segment %s length: %v", s, err)
	}
	data := make([]byte, s.len)
	n, err := r.Read(data)
	if err != nil && n != int(s.len) {
		return fmt.Errorf("failed to read segment value: err %v, read len %d, expect len %d", err, n, s.len)
	}

	msg, err := getMessageFromType(int(s.typ))
	if err != nil {
		return fmt.Errorf("failed to create message by type %d: %w", s.typ, err)
	}
	if err = proto.Unmarshal(data, msg); err != nil {
		return fmt.Errorf("failed to unmarshal segment msg %d: %w", s.typ, err)
	}
	s.val = msg
	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Regenerate the metadata backup — the file is truncated and cannot be safely parsed
2. Check for free-space or write errors that caused the original backup to be cut short
3. Verify the backup file's integrity (size/checksum) against its source
4. Ensure the storage holding the backup is healthy before re-reading

fi, err := os.Stat(backupPath)
if err != nil || fi.Size() < minFooterHeaderBytes { return fmt.Errorf("backup too small/truncated: %s", backupPath) }

if err := seg.Unmarshal(r); err != nil {
    if strings.Contains(err.Error(), "failed to read segment") || errors.Is(err, io.ErrUnexpectedEOF) {
        return fmt.Errorf("corrupt/truncated backup segment header: %w", err)
    }
    return err
}

When it happens

Trigger: Calling ReadFooter on a stream truncated right after a segment type byte; a corrupted backup file with a partial final segment; an underlying read I/O error (device error, closed handle).

Common situations: Backup interrupted mid-write leaving a partial trailing segment; copying/truncating a backup file; reading a backup from a flaky network mount.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• failed to read segment type: %v
• failed to read segment value: err %v, read len %d, expect le
• Unable to skip %s bytes (position=%s, fileSize=%s): %s
• failed to write EOS: err %w, write len %d, expect len 4
• failed to write footer data: err %w, write len %d, expect le

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