geektutu/7days-golang · error
invalid checksum
Error message
invalid checksum
What it means
The day3-tree meta page passes the magic check but its checksum field does not match the recomputed hash of the meta struct, indicating the metadata page was corrupted or written without updating the checksum.
Source
Thrown at gee-bolt/day3-tree/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 from a known-good backup or fall back to the secondary meta page
- Re-create the database and reload data
- Ensure every meta mutation recomputes m.checksum = m.sum64() before flush
- Add fsync-before-rename style write discipline to avoid torn pages
Example fix
// before m.freelist = newPage _ = m.writeTo(page) // stale checksum -> invalid checksum // after m.freelist = newPage m.checksum = m.sum64() _ = m.writeTo(page)
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
- Update checksum as part of every meta write transaction
- Enable clean shutdown handling (SIGTERM handling) before writes
- Maintain backups and test restore procedures
- Avoid concurrent uncoordinated writers to the same file
When it happens
Trigger: Torn write during a crash, checksum not recomputed after mutating meta fields, external edits to the file, or reading a partially flushed page.
Common situations: Kill -9/power loss between meta update and checksum write; running day3 code against a file mutated by day1 tooling; concurrent writers without locking.
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/2ab771257be8958e.
Report an issue: GitHub.