geektutu/7days-golang · error
invalid checksum
Error message
invalid checksum
What it means
The meta page's magic number matched but its stored checksum no longer equals the recomputed xxhash over the meta struct, so validate() deems the page corrupt. This guards against torn writes and bit rot in the metadata page.
Source
Thrown at gee-bolt/day1-pages/meta.go:30
type meta struct {
magic uint32
pageSize uint32
pgid uint64
checksum uint64
}
func (m *meta) sum64() uint64 {
var h = fnv.New64a()
_, _ = h.Write((*[unsafe.Offsetof(meta{}.checksum)]byte)(unsafe.Pointer(m))[:])
return h.Sum64()
}
func (m *meta) validate() error {
if m.magic != magic {
return errors.New("invalid magic number")
}
if m.checksum != m.sum64() {
return errors.New("invalid checksum")
}
return nil
}
View on GitHub (pinned to cf36443821)
Solutions
- Restore the database from backup — the meta page is inconsistent
- If a second meta page exists, fall back to the other valid meta copy
- Re-create the database and re-import data from another source
- Never write the meta struct without recomputing and storing m.sum64() into the checksum field
Example fix
// before m.magic = magic // forgot: m.checksum = m.sum64() -> invalid checksum on next open // after m.magic = magic m.checksum = m.sum64()
Defensive patterns
Strategy: validation
Validate before calling
func metaIsConsistent(m *meta) bool { return m.checksum == m.sum64() } Type guard
func hasValidChecksum(m *meta) bool { return m != nil && m.checksum == m.sum64() } Prevention
- Always recompute checksum after any meta mutation, before writing
- Use atomic write patterns (write temp file + fsync + rename)
- Restore from backup on checksum failure instead of patching bytes
- Avoid copying DB files while writers are active
When it happens
Trigger: Process crash mid-write leaving a partially updated meta page, external modification of the file, disk corruption, or writing meta without updating the checksum field.
Common situations: Power loss or kill -9 during a commit; editing the DB with a hex editor; copying the file while it was being written; a buggy custom writer that forgot to recompute sum64().
Understand the failure class
Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.
Related errors
AI-assisted analysis of geektutu/7days-golang@cf36443821 (2026-09-03).
Data as JSON: /api/errors/ce22733298c82f72.
Report an issue: GitHub.